api-error

Source: crates/lvcs-api/src/error.rs.

/// `data` of every JSON-RPC error the daemon or `lvcs mcp` answers.
///
/// Decision 163: what went wrong, said for a reader who has never seen
/// LVCS, and how to recover from it.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct ErrorData {
    /// What went wrong, in plain words.
    pub reason: String,
    /// How to recover: a `recover` value among the error code's.
    pub recover: String,
    /// The one action that recovers, present exactly when `recover` isn't
    /// `none`.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub next: Option<Next>,
    /// The `rule` value that refused the request, present exactly when the
    /// code is `rejected`.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub rule: Option<String>,
    /// How long to wait before sending the same request again, present
    /// exactly when `recover` is `retry_after`.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub retry_after_ms: Option<u64>,
    /// What the secret scan flagged, present exactly when the code is
    /// `secret_detected`.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub secret: Option<SecretHit>,
}

/// The one action that recovers from an error (decision 163).
///
/// `op` with `params` is a whole request to send as given; `op` alone is
/// the same request sent again, with the same params; `cli` is a command
/// line, starting `lvcs `, to run in the project root; `candidates`
/// alone (decision 243) are the ids a prefix or alias named more than one
/// of, at most `CANDIDATES_MAX`: send the request again naming one.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct Next {
    /// An `op` value.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub op: Option<String>,
    /// The params to send `op` with.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub params: Option<serde_json::Value>,
    /// A command line to run instead.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub cli: Option<String>,
    /// The ids an ambiguous prefix named, one of which to name instead.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub candidates: Vec<String>,
}

/// What the secret scan flagged (design §15, decisions 147 and 163).
///
/// `start..end` are code points of the request's text at its base. An edit
/// is held uncommitted, whoever its author is, and `held` is what
/// `secret.confirm` takes; a message's text or a mirror save has no edit
/// to hold, and `held` is absent.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct SecretHit {
    /// The document.
    pub address: String,
    /// The flagged text's first code point.
    pub start: usize,
    /// The code point past it.
    pub end: usize,
    /// The scan pattern that flagged it: a known token format's name, or
    /// `entropy`.
    pub pattern: String,
    /// The held edit's id, for `secret.confirm`.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub held: Option<String>,
}