nereid 0.9.0

// SPDX-FileCopyrightText: 2026 Bruno Meilick
// SPDX-License-Identifier: LicenseRef-Nereid-FreeUse-NoCopy-NoDerivatives
//
// All rights reserved.
//
// This file is part of Nereid and is proprietary software.
// Unauthorized copying, modification, or distribution is prohibited.

//! Revision-gated diagram mutations and change deltas (optimistic concurrency).
//!
//! Agents and the TUI edit through typed ops (`SeqOp`, `FlowOp`) applied with a `base_rev`
//! OCC check against `diagram.rev()`. Successful batches bump the revision and return a
//! coarse `Delta` of added/removed/updated `ObjectRef`s for UI refresh and MCP `diagram_diff`.
//! Batches are all-or-nothing on a cloned AST; sequence structure must remain Mermaid-export
//! valid (contiguous section membership; nested messages also on ancestor sections).

use std::collections::HashSet;
use std::fmt;

use crate::format::mermaid::flowchart::MermaidIdentError;
use crate::model::seq_ast::{
    SequenceBlock, SequenceBlockKind, SequenceSection, SequenceSectionKind,
};
use crate::model::{
    CategoryPath, Diagram, DiagramAst, DiagramId, DiagramKind, FlowEdge, FlowNode, FlowchartAst,
};
use crate::model::{ObjectId, ObjectRef, SequenceAst, SequenceMessage, SequenceMessageKind};
use crate::model::{SequenceParticipant, SymbolAnchor, SymbolAnchorError, XRefId};

/// Maximum nested block depth, matching the sequence Mermaid parser.
pub const MAX_SEQ_BLOCK_NEST_DEPTH: usize = 8;

/// Kind-tagged diagram mutation (sequence, flowchart, or unsupported xref batch).
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum Op {
    Seq(SeqOp),
    Flow(FlowOp),
    XRef(XRefOp),
}

/// Sequence-diagram mutation: participants, messages, blocks, sections, membership.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum SeqOp {
    AddParticipant {
        participant_id: ObjectId,
        mermaid_name: String,
    },
    UpdateParticipant {
        participant_id: ObjectId,
        patch: SeqParticipantPatch,
    },
    SetParticipantNote {
        participant_id: ObjectId,
        note: Option<String>,
    },
    SetParticipantSymbol {
        participant_id: ObjectId,
        symbol: Option<SymbolAnchor>,
    },
    RemoveParticipant {
        participant_id: ObjectId,
    },
    AddMessage {
        message_id: ObjectId,
        from_participant_id: ObjectId,
        to_participant_id: ObjectId,
        kind: SequenceMessageKind,
        arrow: Option<String>,
        text: String,
        order_key: i64,
        /// When set, attach the new message to this section after creation.
        section_id: Option<ObjectId>,
    },
    UpdateMessage {
        message_id: ObjectId,
        patch: SeqMessagePatch,
    },
    RemoveMessage {
        message_id: ObjectId,
    },
    /// Attach, move, or detach a message's block-section membership.
    ///
    /// `section_id: None` detaches the message from every section.
    SetMessageSection {
        message_id: ObjectId,
        section_id: Option<ObjectId>,
    },
    AddBlock {
        block_id: ObjectId,
        kind: SequenceBlockKind,
        header: Option<String>,
        parent_block_id: Option<ObjectId>,
        main_section_id: ObjectId,
    },
    UpdateBlock {
        block_id: ObjectId,
        patch: SeqBlockPatch,
    },
    RemoveBlock {
        block_id: ObjectId,
    },
    AddSection {
        section_id: ObjectId,
        block_id: ObjectId,
        kind: SequenceSectionKind,
        header: Option<String>,
    },
    UpdateSection {
        section_id: ObjectId,
        patch: SeqSectionPatch,
    },
    RemoveSection {
        section_id: ObjectId,
    },
}

/// Partial update for a sequence block header (`Some(None)` clears).
#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub struct SeqBlockPatch {
    pub header: Option<Option<String>>,
}

/// Partial update for a sequence section header (`Some(None)` clears).
#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub struct SeqSectionPatch {
    pub header: Option<Option<String>>,
}

/// Partial update for a sequence participant.
#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub struct SeqParticipantPatch {
    pub mermaid_name: Option<String>,
}

/// Partial update for a sequence message.
#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub struct SeqMessagePatch {
    pub from_participant_id: Option<ObjectId>,
    pub to_participant_id: Option<ObjectId>,
    pub kind: Option<SequenceMessageKind>,
    pub arrow: Option<String>,
    pub text: Option<String>,
    pub order_key: Option<i64>,
}

/// Flowchart mutation: nodes, edges, notes, and Frigg symbol anchors.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum FlowOp {
    AddNode {
        node_id: ObjectId,
        label: String,
        shape: Option<String>,
    },
    UpdateNode {
        node_id: ObjectId,
        patch: FlowNodePatch,
    },
    SetNodeMermaidId {
        node_id: ObjectId,
        mermaid_id: Option<String>,
    },
    SetNodeNote {
        node_id: ObjectId,
        note: Option<String>,
    },
    SetNodeSymbol {
        node_id: ObjectId,
        symbol: Option<SymbolAnchor>,
    },
    RemoveNode {
        node_id: ObjectId,
    },
    AddEdge {
        edge_id: ObjectId,
        from_node_id: ObjectId,
        to_node_id: ObjectId,
        label: Option<String>,
        connector: Option<String>,
        style: Option<String>,
    },
    UpdateEdge {
        edge_id: ObjectId,
        patch: FlowEdgePatch,
    },
    RemoveEdge {
        edge_id: ObjectId,
    },
}

/// Partial update for a flow node.
#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub struct FlowNodePatch {
    pub label: Option<String>,
    pub shape: Option<String>,
}

/// Partial update for a flow edge.
#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub struct FlowEdgePatch {
    pub from_node_id: Option<ObjectId>,
    pub to_node_id: Option<ObjectId>,
    pub label: Option<String>,
    pub connector: Option<String>,
    pub style: Option<String>,
}

/// Session-level xref mutation (not applied via `apply_ops` today; MCP uses dedicated tools).
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum XRefOp {
    Add { xref_id: XRefId, from: ObjectRef, to: ObjectRef, kind: String, label: Option<String> },
    Remove { xref_id: XRefId },
}

/// Outcome of a successful `apply_ops` batch.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ApplyResult {
    pub new_rev: u64,
    pub applied: usize,
    pub delta: Delta,
}

/// Coarse object-level change set from an op batch (added / removed / updated `ObjectRef`s).
///
/// Net effect after collapsing intermediate states within the same batch (e.g. add-then-remove
/// cancels out; update of an already-added ref stays in `added` only).
#[derive(Debug, Clone, PartialEq, Eq, Default)]
pub struct Delta {
    pub added: Vec<ObjectRef>,
    pub removed: Vec<ObjectRef>,
    pub updated: Vec<ObjectRef>,
}

/// Collapses per-op `ObjectRef` events into a net [`Delta`] for one batch.
#[derive(Debug, Default)]
struct DeltaBuilder {
    added: HashSet<ObjectRef>,
    removed: HashSet<ObjectRef>,
    updated: HashSet<ObjectRef>,
}

impl DeltaBuilder {
    fn record_added(&mut self, object_ref: ObjectRef) {
        self.removed.remove(&object_ref);
        self.updated.remove(&object_ref);
        self.added.insert(object_ref);
    }

    fn record_removed(&mut self, object_ref: ObjectRef) {
        self.added.remove(&object_ref);
        self.updated.remove(&object_ref);
        self.removed.insert(object_ref);
    }

    fn record_updated(&mut self, object_ref: ObjectRef) {
        // Already added or removed in this batch: keep the stronger lifecycle event.
        if self.added.contains(&object_ref) || self.removed.contains(&object_ref) {
            return;
        }
        self.updated.insert(object_ref);
    }

    fn finish(self) -> Delta {
        let mut added = self.added.into_iter().collect::<Vec<_>>();
        let mut removed = self.removed.into_iter().collect::<Vec<_>>();
        let mut updated = self.updated.into_iter().collect::<Vec<_>>();

        sort_object_refs(&mut added);
        sort_object_refs(&mut removed);
        sort_object_refs(&mut updated);

        Delta { added, removed, updated }
    }
}

fn sort_object_refs(refs: &mut [ObjectRef]) {
    refs.sort_by(|a, b| {
        a.diagram_id()
            .cmp(b.diagram_id())
            .then_with(|| a.category().cmp(b.category()))
            .then_with(|| a.object_id().cmp(b.object_id()))
    });
}

/// Apply ops under OCC if `base_rev` matches `diagram.rev()`, then bump revision once.
///
/// Empty `ops` is a no-op that keeps the current revision. `Op::XRef` is rejected; session
/// xrefs use dedicated MCP tools. Sequence batches re-validate block structure via export.
///
/// # Errors
///
/// [`ApplyError::Conflict`] on stale `base_rev`; also kind mismatches, missing/duplicate ids,
/// invalid Mermaid identifiers/message text, or export-invalid sequence structure after the batch.
pub fn apply_ops(
    diagram: &mut Diagram,
    base_rev: u64,
    ops: &[Op],
) -> Result<ApplyResult, ApplyError> {
    let current_rev = diagram.rev();
    if base_rev != current_rev {
        return Err(ApplyError::Conflict { base_rev, current_rev });
    }

    if ops.is_empty() {
        return Ok(ApplyResult { new_rev: current_rev, applied: 0, delta: Delta::default() });
    }

    let mut new_ast = diagram.ast().clone();
    let diagram_id = diagram.diagram_id().clone();
    let mut delta = DeltaBuilder::default();

    for op in ops {
        match op {
            Op::Seq(seq_op) => {
                let DiagramAst::Sequence(ast) = &mut new_ast else {
                    return Err(ApplyError::KindMismatch {
                        diagram_kind: diagram.kind(),
                        op_kind: OpKind::Seq,
                    });
                };
                apply_seq_op(&diagram_id, ast, seq_op, &mut delta)?;
            }
            Op::Flow(flow_op) => {
                let DiagramAst::Flowchart(ast) = &mut new_ast else {
                    return Err(ApplyError::KindMismatch {
                        diagram_kind: diagram.kind(),
                        op_kind: OpKind::Flow,
                    });
                };
                apply_flow_op(&diagram_id, ast, flow_op, &mut delta)?;
            }
            Op::XRef(_) => {
                return Err(ApplyError::UnsupportedOp { op_kind: OpKind::XRef });
            }
        }
    }

    if let DiagramAst::Sequence(ast) = &new_ast {
        validate_sequence_block_structure(ast)?;
    }

    diagram.set_ast(new_ast).map_err(|mismatch| {
        let op_kind = match mismatch.found() {
            DiagramKind::Sequence => OpKind::Seq,
            DiagramKind::Flowchart | DiagramKind::Class | DiagramKind::Er | DiagramKind::Gantt => {
                OpKind::Flow
            }
        };
        ApplyError::KindMismatch { diagram_kind: mismatch.expected(), op_kind }
    })?;
    diagram.bump_rev();
    let new_rev = diagram.rev();

    Ok(ApplyResult { new_rev, applied: ops.len(), delta: delta.finish() })
}

/// High-level op family used in kind-mismatch errors.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum OpKind {
    Seq,
    Flow,
    XRef,
}

/// Object category for existence / uniqueness errors.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ObjectKind {
    SeqParticipant,
    SeqMessage,
    SeqBlock,
    SeqSection,
    FlowNode,
    FlowEdge,
}

/// Failures from [`apply_ops`]: OCC conflicts, missing ids, structure, identifiers.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum ApplyError {
    /// OCC rejection: caller's `base_rev` does not match `diagram.rev()`.
    Conflict {
        base_rev: u64,
        current_rev: u64,
    },
    /// Op family does not match the diagram AST kind (e.g. `SeqOp` on flowchart).
    KindMismatch {
        diagram_kind: DiagramKind,
        op_kind: OpKind,
    },
    /// Op family not applied through this path (currently `XRef`).
    UnsupportedOp {
        op_kind: OpKind,
    },
    AlreadyExists {
        kind: ObjectKind,
        object_id: ObjectId,
    },
    NotFound {
        kind: ObjectKind,
        object_id: ObjectId,
    },
    /// Edge endpoint references a node id absent from the flowchart AST.
    MissingFlowNode {
        node_id: ObjectId,
    },
    InvalidSeqParticipantMermaidName {
        mermaid_name: String,
        reason: MermaidIdentError,
    },
    DuplicateSeqParticipantMermaidName {
        mermaid_name: String,
        participant_id: ObjectId,
    },
    InvalidFlowNodeMermaidId {
        mermaid_id: String,
        reason: MermaidIdentError,
    },
    DuplicateFlowNodeMermaidId {
        mermaid_id: String,
        node_id: ObjectId,
    },
    InvalidSymbolAnchor {
        source: SymbolAnchorError,
    },
    InvalidSeqSectionKind {
        block_id: ObjectId,
        block_kind: SequenceBlockKind,
        section_kind: SequenceSectionKind,
    },
    InvalidSeqSectionNotEmpty {
        section_id: ObjectId,
    },
    InvalidSeqSectionIsMain {
        section_id: ObjectId,
    },
    InvalidSeqBlockNesting {
        block_id: ObjectId,
        reason: String,
    },
    InvalidSeqBlockStructure {
        reason: String,
    },
    /// Empty or whitespace-only sequence message text (parser would reject on reload).
    InvalidSeqMessageText {
        text: String,
    },
}

impl fmt::Display for ApplyError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::Conflict { base_rev, current_rev } => {
                write!(f, "stale base_rev (base_rev={base_rev}, current_rev={current_rev})")
            }
            Self::KindMismatch { diagram_kind, op_kind } => {
                write!(f, "op kind mismatch (diagram_kind={diagram_kind:?}, op_kind={op_kind:?})")
            }
            Self::UnsupportedOp { op_kind } => write!(f, "unsupported op kind ({op_kind:?})"),
            Self::AlreadyExists { kind, object_id } => {
                write!(f, "object already exists ({kind:?}, id={object_id})")
            }
            Self::NotFound { kind, object_id } => {
                write!(f, "object not found ({kind:?}, id={object_id})")
            }
            Self::MissingFlowNode { node_id } => write!(f, "flow node not found (id={node_id})"),
            Self::InvalidSeqParticipantMermaidName { mermaid_name, reason } => {
                write!(f, "invalid sequence participant Mermaid name '{mermaid_name}': {reason}")
            }
            Self::DuplicateSeqParticipantMermaidName { mermaid_name, participant_id } => {
                write!(
                    f,
                    "sequence participant Mermaid name '{mermaid_name}' is already used by participant {participant_id}"
                )
            }
            Self::InvalidFlowNodeMermaidId { mermaid_id, reason } => {
                write!(f, "invalid flow node Mermaid id '{mermaid_id}': {reason}")
            }
            Self::DuplicateFlowNodeMermaidId { mermaid_id, node_id } => {
                write!(f, "flow node Mermaid id '{mermaid_id}' is already used by node {node_id}")
            }
            Self::InvalidSymbolAnchor { source } => write!(f, "{source}"),
            Self::InvalidSeqSectionKind { block_id, block_kind, section_kind } => write!(
                f,
                "section kind {section_kind:?} is not valid under block {block_id} ({block_kind:?})"
            ),
            Self::InvalidSeqSectionNotEmpty { section_id } => write!(
                f,
                "section {section_id} still has messages; detach them before removing the section"
            ),
            Self::InvalidSeqSectionIsMain { section_id } => {
                write!(f, "cannot remove main section {section_id}")
            }
            Self::InvalidSeqBlockNesting { block_id, reason } => {
                write!(f, "invalid block nesting for {block_id}: {reason}")
            }
            Self::InvalidSeqBlockStructure { reason } => {
                write!(
                    f,
                    "invalid sequence block structure: {reason} (section messages must be contiguous in order_key order; nested messages must also belong to ancestor sections)"
                )
            }
            Self::InvalidSeqMessageText { text } => {
                write!(f, "sequence message text must be non-empty (got {text:?})")
            }
        }
    }
}

impl std::error::Error for ApplyError {}

include!("ops_impl.rs");

#[cfg(test)]
mod tests;