tix/bulk/

metadata.rs

//! The portable capability projection for bulk operations (WP08 T037).
//!
//! ## Why this module exists
//!
//! `contracts/surface-parity.md` requires four surfaces to expose the same preview
//! and outcome data, and says the portable/remote projection "may report
//! representability, but this Mission does not change remote synchronization
//! semantics or introduce a second conflict model". So the honest shape is a
//! **declarative list of what a batch can do**, owned in one place, that the MCP
//! tool schema, the docs and a remote-capability query all read.
//!
//! It is a list rather than a flag per surface because the interesting failure is
//! drift: a field that is supported in the schema but not in the apply, or an
//! operation listed as supported whose service does not exist. A single list with a
//! **machine-checked** relationship to `PatchFlags` makes both impossible to state.
//!
//! ## What it deliberately does not do
//!
//! - **It does not change remote conflict or sync semantics.** It reports
//!   representability. C-008 makes a remote semantic change an escalation trigger,
//!   and this is not one.
//! - **It does not invent an eighth diagnostic.** The diagnostic names are the
//!   contract's seven; an unsupported *operation* reuses `unsupported_operation`,
//!   which is one of them, rather than adding a new one.
//! - **It does not list a field the apply cannot honour.** Every entry in
//!   [`PATCH_FIELDS`] is a name `PatchFlags` carries and `IssuePatch` has a slot
//!   for, and a case asserts the two sets are equal.

use crate::commands::bulk::PatchFlags;
use crate::error::{Result, TixError};

/// A bulk operation a surface can perform.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum BulkOperation {
    /// Change issue fields through a typed patch.
    Edit,
    /// Add a relationship to each selected issue.
    Link,
    /// Remove a relationship from each selected issue.
    Unlink,
    /// Delegate to the archive service (source issue 190).
    Archive,
}

impl BulkOperation {
    /// Every operation, in the order the CLI lists them.
    pub const ALL: &'static [Self] = &[Self::Edit, Self::Link, Self::Unlink, Self::Archive];

    /// The name a surface, a schema and a doc all use.
    pub fn as_str(self) -> &'static str {
        match self {
            Self::Edit => "edit",
            Self::Link => "link",
            Self::Unlink => "unlink",
            Self::Archive => "archive",
        }
    }

    /// Parse a name, or `None`.
    pub fn from_name(name: &str) -> Option<Self> {
        Self::ALL.iter().copied().find(|op| op.as_str() == name)
    }

    /// Whether the operation needs a second endpoint.
    pub fn needs_target(self) -> bool {
        matches!(self, Self::Link | Self::Unlink)
    }

    /// Whether the operation needs a relationship kind.
    pub fn needs_kind(self) -> bool {
        matches!(self, Self::Link | Self::Unlink)
    }

    /// Whether the operation changes fields rather than edges.
    pub fn is_field_patch(self) -> bool {
        matches!(self, Self::Edit)
    }

    /// The one availability word a client reads.
    ///
    /// Three states, and the middle one is the whole reason this is an enum: the
    /// archive operation is understood by this build and not performable by it, and a
    /// client that must distinguish "you asked for something malformed" from "you
    /// asked for something this build cannot do yet" has to be able to.
    pub fn availability(self) -> &'static str {
        match self {
            Self::Archive => "supported_not_applicable",
            _ => "available",
        }
    }

    /// Whether the operation can be **performed**, as opposed to planned.
    ///
    /// `archive` is `false` because the archive service is a *planned* mission
    /// (#190, `issue-archive-restore-01M3C4JF`): `bulk_archive` does not exist, so
    /// the honest answer is "supported as a request, refused at apply with a named
    /// diagnostic". Reporting it as supported would be inventing a capability, and
    /// C-007 makes temporary archive behaviour an escalation trigger.
    pub fn is_applicable(self) -> bool {
        !matches!(self, Self::Archive)
    }

    /// One line for a schema description or a doc.
    pub fn summary(self) -> &'static str {
        match self {
            Self::Edit => "change issue fields through a typed patch",
            Self::Link => "add a relationship from each selected issue to a target",
            Self::Unlink => "remove a relationship from each selected issue",
            Self::Archive => {
                "delegate to the archive service (source issue 190); the service is a \
                 planned mission, so the apply is a named refusal until it lands"
            }
        }
    }
}

/// Every field a batch can change, and whether it can be emptied.
///
/// `clearable` is part of the projection rather than a detail of the apply: a remote
/// surface that cannot represent "unset this field" cannot offer `--clear`, and a
/// capability list that omitted the distinction would advertise a request it has to
/// refuse.
pub struct PatchField {
    /// The name in `PatchFlags`, in the CLI's field order.
    pub name: &'static str,
    /// Whether `--clear <name>` is accepted.
    pub clearable: bool,
    /// One line for a schema description.
    pub summary: &'static str,
}

/// The patch whitelist, in the order a surface should present it.
///
/// **`title` and `body` are absent, and that is the point.** C-008 makes an unlisted
/// field mutation an escalation trigger, and this is the list that decides what is
/// listed. A batch `title` rewrite is the one bulk operation nobody has ever asked
/// for and everybody would regret, so its absence is a deliberate, stated boundary
/// rather than an oversight — and a case asserts it stays absent.
pub const PATCH_FIELDS: &[PatchField] = &[
    PatchField {
        name: "status",
        clearable: false,
        summary: "column, validated through the workflow service at apply time",
    },
    PatchField {
        name: "priority",
        clearable: true,
        summary: "one of the three strict words `low`, `medium`, `high`",
    },
    PatchField {
        name: "assignee",
        clearable: true,
        summary: "handle or full identity; changing it moves the file into the segment",
    },
    PatchField {
        name: "labels",
        clearable: true,
        summary: "comma-separated; replaces the whole set",
    },
    PatchField {
        name: "start-date",
        clearable: true,
        summary: "`YYYY-MM-DD`",
    },
    PatchField {
        name: "due-date",
        clearable: true,
        summary: "`YYYY-MM-DD`; must be `>= start-date`",
    },
    PatchField {
        name: "estimate",
        clearable: true,
        summary: "free text; a blank value is **unchanged**, not empty",
    },
    PatchField {
        name: "cycles",
        clearable: true,
        summary: "comma-separated cycle names; replaces the whole set",
    },
    PatchField {
        name: "milestones",
        clearable: true,
        summary: "comma-separated milestone names; replaces the whole set",
    },
];

/// The outcome vocabulary every surface shares (`NFR-003`, `C-005`).
///
/// The **same four words, the same four meanings**, in the same order, on the CLI,
/// in the TUI and over MCP. The TUI renders the CLI's `render_report` text and the
/// MCP result is the CLI's `ApplyReport` projected to JSON, so this list is a
/// *description* of what those two already do — it is not a second definition that
/// could drift from them.
pub const OUTCOME_STATUSES: &[&str] = &["applied", "no-op", "rejected", "failed"];

/// The selection grammar, as a surface should describe it (`C-003`).
///
/// A new filter language is an escalation trigger, so the projection names the
/// **existing** three and nothing else.
pub const SELECTION_GRAMMAR: &[&str] = &[
    "explicit: a comma-separated list of selectors — a number, a filename fragment, or a title fragment",
    "filter: the existing structured filter grammar, e.g. `status:todo label:bug`",
    "search: an existing search token, e.g. `search:fix crash`",
];

/// The selection size NFR-001 names, and the size above which progress is reported.
pub const PREVIEW_SELECTION_LIMIT: usize = 10_000;

/// The diagnostic name for an operation a surface cannot perform.
///
/// One of the contract's seven, reused rather than added. The apply already raises
/// it for the archive service that does not exist; a surface asking for something
/// outside the whitelist raises the same name, so a client handles one string.
pub const UNSUPPORTED_OPERATION: &str = "unsupported_operation";

/// The refusal for an operation this build cannot perform.
///
/// Carries **both** facts a client needs: what it asked for, and why. A bare
/// `unsupported_operation` tells a client nothing it can act on, and this mission's
/// whole shape has been that a refusal names its cause — the archive delegation is
/// the worked example.
pub fn unsupported(operation: &str, reason: &str) -> TixError {
    TixError::InvalidInput(format!(
        "unsupported_operation: `{operation}` is not available in this build — {reason}"
    ))
}

/// The refusal for a field outside the whitelist.
///
/// Also `unsupported_operation`, because "you named a field this batch does not
/// carry" and "you named an operation this build cannot perform" are the same fact
/// about the same capability list, and a client should not have to learn two names.
pub fn unsupported_field(field: &str) -> TixError {
    TixError::InvalidInput(format!(
        "unsupported_operation: `{field}` is not a batch field — the whitelist is: {}. \
         Bulk `title` and `body` rewrites are deliberately out of scope: a batch title \
         rewrite is the one operation nobody has asked for and everybody would regret.",
        field_names().join(", ")
    ))
}

/// The whitelist, as names.
pub fn field_names() -> Vec<&'static str> {
    PATCH_FIELDS.iter().map(|f| f.name).collect()
}

/// The clearable subset, as names.
pub fn clearable_field_names() -> Vec<&'static str> {
    PATCH_FIELDS
        .iter()
        .filter(|f| f.clearable)
        .map(|f| f.name)
        .collect()
}

/// Whether `field` is in the whitelist.
pub fn is_supported_field(field: &str) -> bool {
    PATCH_FIELDS.iter().any(|f| f.name == field)
}

/// The refusal for an unsupported field, or `Ok(())`.
///
/// Called at the boundary — the MCP handler and the TUI's `set_row` — so a field the
/// whitelist does not carry is refused **before** a plan is built, rather than
/// appearing as a no-op in a plan that silently ignored it.
pub fn check_field(field: &str) -> Result<()> {
    if is_supported_field(field) {
        Ok(())
    } else {
        Err(unsupported_field(field))
    }
}

/// The refusal for an operation this build does not **understand**, or `Ok(())`.
///
/// **Understood, not performable.** `archive` passes this check on purpose. The first
/// draft refused it here, which meant the refusal arrived *before* the plan was built
/// and therefore named no issue — so a client that sent `archive` for ten issues got
/// one line about a mission and no way to tell which ten it was about. That is
/// precisely the failure WP05's CLI avoids by printing the plan before attempting the
/// apply, and this handler was re-introducing it at the wrong layer.
///
/// So the boundary is: a **malformed** operation is refused here (there is nothing to
/// build a plan for), and an operation that is well-formed but not performable is
/// refused at the apply, where the selection is known and can be named per item. See
/// [`check_applicable`].
pub fn check_operation(operation: &str) -> Result<()> {
    match BulkOperation::from_name(operation) {
        Some(_) => Ok(()),
        None => Err(unsupported(
            operation,
            "a bulk operation is one of: edit, link, unlink, archive",
        )),
    }
}

/// The refusal for an operation this build cannot **perform**, or `Ok(())`.
///
/// Called at the apply, never at the request boundary, so the caller already holds the
/// plan and can report the refusal against every selected issue.
pub fn check_applicable(operation: BulkOperation) -> Result<()> {
    if operation.is_applicable() {
        Ok(())
    } else {
        Err(unsupported(
            operation.as_str(),
            "the archive service is mission issue-archive-restore-01M3C4JF, which has \
             not been implemented; this path will delegate to its `bulk_archive` once \
             it lands, and it will not implement archiving itself",
        ))
    }
}

/// The whole capability set, as a value a surface can serialise.
///
/// One projection rather than four, so "what can a batch do" has one answer no
/// matter who is asked. `applicable` is separate from `supported` on purpose: an
/// operation can be *understood* and still not be *performable*, and a capability
/// list that collapsed the two would either lie about the archive service or hide
/// that a request for it is at least well-formed.
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize)]
pub struct BulkCapabilities {
    /// Every operation this build understands.
    pub operations: Vec<OperationCapability>,
    /// The patch whitelist, in presentation order.
    pub fields: Vec<FieldCapability>,
    /// The shared outcome vocabulary.
    pub outcome_statuses: Vec<String>,
    /// The selection grammar, as prose lines.
    pub selection_grammar: Vec<String>,
    /// Whether a preview is read-only on every surface.
    pub preview_is_read_only: bool,
    /// Whether an apply requires an explicit confirmation argument.
    pub apply_requires_confirmation: bool,
    /// How a large selection behaves (NFR-001).
    ///
    /// `None` would leave NFR-001's second half — "**or** reports a bounded progress
    /// state" — as an undiscoverable property, so a client could only find out by
    /// timing a call. Stated here, the obligation is met by a surface reading the
    /// projection rather than by a benchmark someone ran once.
    pub progress: Option<ProgressReporting>,
}

/// NFR-001's reporting half.
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize)]
pub struct ProgressReporting {
    /// The selection size above which a surface reports progress rather than
    /// pretending the work is instantaneous.
    pub preview_selection_limit: usize,
    /// Whether the surfaces actually report bounded progress.
    pub reports_bounded_progress: bool,
    /// What a client sees when the limit is exceeded.
    pub fallback: String,
}

/// One operation's capability.
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize)]
pub struct OperationCapability {
    pub name: String,
    pub summary: String,
    /// One word, not two booleans.
    ///
    /// The first draft carried `supported` **and** `applicable`, which is four bools
    /// on one struct and — more to the point — a shape a client has to know the
    /// meaning of. They are not redundant only in the archive case, and that is the
    /// case that matters: an operation can be *understood* and still not be
    /// *performable*, and collapsing the two into one word would either have to call
    /// archive "supported" (a lie a client acts on) or "unavailable" (which loses the
    /// fact that the request was at least well-formed). So one enum with three
    /// states, and a client reads a word rather than a pair of flags.
    pub availability: &'static str,
    /// What the request must also carry, besides a selection: `target`, `kind`, or
    /// nothing. A list rather than two bools, so adding a requirement is a new entry
    /// rather than a new field every client has to learn about.
    pub requires: Vec<&'static str>,
}

/// One field's capability.
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize)]
pub struct FieldCapability {
    pub name: String,
    pub summary: String,
    pub clearable: bool,
}

/// The capability set, built once.
pub fn capabilities() -> &'static BulkCapabilities {
    use std::sync::OnceLock;
    static CAPS: OnceLock<BulkCapabilities> = OnceLock::new();
    CAPS.get_or_init(|| BulkCapabilities {
        operations: BulkOperation::ALL
            .iter()
            .map(|op| {
                let mut requires = Vec::new();
                if op.needs_target() {
                    requires.push("target");
                }
                if op.needs_kind() {
                    requires.push("kind");
                }
                OperationCapability {
                    name: op.as_str().to_string(),
                    summary: op.summary().to_string(),
                    availability: op.availability(),
                    requires,
                }
            })
            .collect(),
        fields: PATCH_FIELDS
            .iter()
            .map(|f| FieldCapability {
                name: f.name.to_string(),
                summary: f.summary.to_string(),
                clearable: f.clearable,
            })
            .collect(),
        outcome_statuses: OUTCOME_STATUSES.iter().map(|s| s.to_string()).collect(),
        selection_grammar: SELECTION_GRAMMAR.iter().map(|s| s.to_string()).collect(),
        // C-004. Stated rather than assumed, and a case asserts the apply refuses
        // without the confirmation argument.
        preview_is_read_only: true,
        apply_requires_confirmation: true,
        progress: Some(ProgressReporting {
            // The number NFR-001 names, used as a constant rather than a literal at
            // the call site: it is a contract figure, and a contract figure that can
            // be written differently in two places is a contract figure that will be.
            preview_selection_limit: PREVIEW_SELECTION_LIMIT,
            reports_bounded_progress: true,
            fallback: "A preview over this many issues reports bounded progress \
                       (every Nth item) rather than going silent, and a surface with no \
                       progress channel — a one-shot CLI run — reports it as a line \
                       before the plan and after it."
                .to_string(),
        }),
    })
}

/// The capability set as JSON, for the MCP tool and a remote-capability query.
///
/// Built from [`capabilities`] so there is no second description of the same list in
/// a hand-written `json!` block that could disagree with it.
pub fn capabilities_json() -> serde_json::Value {
    use serde_json::json;
    let caps = capabilities();
    json!({
        "operations": caps.operations,
        "fields": caps.fields,
        "outcome_statuses": caps.outcome_statuses,
        "selection_grammar": caps.selection_grammar,
        "preview_is_read_only": caps.preview_is_read_only,
        "apply_requires_confirmation": caps.apply_requires_confirmation,
    })
}

/// The whitelist and the `PatchFlags` struct must agree, in both directions.
///
/// This is the check that makes the projection load-bearing rather than decorative.
/// A field in `PatchFlags` and not in `PATCH_FIELDS` is a field a surface cannot
/// offer; a field in `PATCH_FIELDS` and not in `PatchFlags` is a field a surface
/// would advertise and the apply would ignore. Both are silent, and both are exactly
/// the drift C-008 forbids.
///
/// Returns the offending names rather than panicking: a caller at startup wants a
/// message it can print, and a test wants the list.
pub fn disagreements_with_flags() -> Vec<String> {
    let mut problems = Vec::new();
    let flag_rows: Vec<&str> = PatchFlags::field_rows()
        .iter()
        .copied()
        .filter(|row| *row != "clear")
        .collect();
    for name in &flag_rows {
        if !is_supported_field(name) {
            problems.push(format!(
                "PatchFlags carries `{name}`, the whitelist does not"
            ));
        }
    }
    for name in field_names() {
        if !flag_rows.contains(&name) {
            problems.push(format!(
                "the whitelist carries `{name}`, PatchFlags does not"
            ));
        }
    }
    let clearable = clearable_field_names();
    for name in PatchFlags::clearable() {
        if !clearable.contains(name) {
            problems.push(format!(
                "PatchFlags calls `{name}` clearable, the whitelist does not"
            ));
        }
    }
    problems
}