patchloom 0.25.0

//! Document operations (JSON, YAML, TOML) for the public library API.
//!
//! Write functions delegate to the tx engine via `execute_as_edit_result`,
//! sharing the same code path as CLI and MCP. Read functions (doc_get,
//! doc_has) load and query directly.
//!
//! Re-exported from api:: via `mod doc; pub use self::doc::*;`.

use std::path::Path;

use crate::containment::PathGuard;
use crate::ops;
use crate::ops::doc::query::{QueryResult, query_get, query_has};
use crate::plan::Operation;

use super::{ApplyMode, EditResult};

/// Derive cwd from a file path (its parent directory).
#[cfg(any(feature = "cli", feature = "files"))]
fn cwd_from_path(path: &Path) -> &Path {
    path.parent().unwrap_or_else(|| Path::new("."))
}

/// Load and parse a JSON/YAML/TOML file for read-only queries.
fn load_doc_value(path: &Path) -> anyhow::Result<serde_json::Value> {
    let path_str = path.to_string_lossy();
    let format = ops::doc::detect_format(&path_str)?;
    let original = crate::files::load_text_strict(path, &path_str)?;
    ops::doc::parse_doc(&original, &format)
}

/// Unified write path: delegates to the tx engine when available (cli/files),
/// falls back to direct mutation when the tx module is not compiled in.
#[cfg(any(feature = "cli", feature = "files"))]
fn doc_write(
    mut op: Operation,
    path: &Path,
    mode: ApplyMode,
    guard: Option<&PathGuard>,
    action: &'static str,
) -> anyhow::Result<EditResult> {
    let abs = super::absolute_for_engine(path).map_err(|e| {
        crate::fallback::EditError::new(
            crate::fallback::EditErrorKind::OperationFailed,
            format!("failed to resolve path {}: {e}", path.display()),
        )
    })?;
    rewrite_op_path(&mut op, abs.to_string_lossy().as_ref());
    // Keep caller path spelling on EditResult (not basename from parent cwd).
    let display = path.to_string_lossy();
    super::execute_as_edit_result_with_path(
        op,
        mode,
        cwd_from_path(&abs),
        guard,
        action,
        None,
        Some(display.as_ref()),
    )
}

/// Put absolutized path into doc/md plan ops so engine join is correct.
#[cfg(any(feature = "cli", feature = "files"))]
fn rewrite_op_path(op: &mut Operation, abs: &str) {
    match op {
        Operation::DocSet { path, .. }
        | Operation::DocDelete { path, .. }
        | Operation::DocMerge { path, .. }
        | Operation::DocAppend { path, .. }
        | Operation::DocPrepend { path, .. }
        | Operation::DocUpdate { path, .. }
        | Operation::DocMove { path, .. }
        | Operation::DocEnsure { path, .. }
        | Operation::DocDeleteWhere { path, .. } => {
            *path = abs.into();
        }
        _ => {}
    }
}

#[cfg(not(any(feature = "cli", feature = "files")))]
fn doc_write(
    op: Operation,
    path: &Path,
    mode: ApplyMode,
    guard: Option<&PathGuard>,
    action: &'static str,
) -> anyhow::Result<EditResult> {
    use crate::ops::doc::MutationResult;
    use crate::write::WritePolicy;

    // Extract the mutation from the operation.
    let (_, mutation) = crate::plan::op_to_doc_mutation(&op)
        .ok_or_else(|| anyhow::anyhow!("doc_write called with non-doc operation"))?;

    let path_str = path.to_string_lossy().into_owned();
    let format = ops::doc::detect_format(&path_str)?;
    let original = crate::files::load_text_strict(path, &path_str)?;
    let value = ops::doc::parse_doc(&original, &format)?;
    let mut new_value = value.clone();

    let result = ops::doc::apply_doc_mutation(&mut new_value, mutation)?;
    if let MutationResult::TypeError(msg) = result {
        return Err(anyhow::Error::new(crate::exit::TypeErrorError { msg }));
    }
    let removed = match &result {
        MutationResult::Removed(n) => *n,
        MutationResult::NoMatch if matches!(action, "doc.delete" | "doc.delete_where") => 0,
        _ => 0,
    };

    let new_content = ops::doc::serialize_value_preserving(&original, &value, &new_value, &format)?;
    let policy = WritePolicy::default();
    // Do not write (or report applied) when the mutation is a no-op.
    let content_changed = original != new_content;
    let (applied, backup_session) = if content_changed {
        super::write_if_apply(path, &new_content, mode, &policy, guard)?
    } else {
        (false, None)
    };
    let mut edit =
        super::build_edit_result(&path_str, original, new_content, applied, action, None);
    edit.removed = removed;
    edit.backup_session = backup_session;
    Ok(edit)
}

/// Set a value at a selector path in a JSON, YAML, or TOML file.
///
/// The file format is detected from the extension. The selector uses
/// patchloom's selector syntax (e.g., `"database.host"`, `"items[0].name"`).
pub fn doc_set(
    path: &Path,
    selector: &str,
    value: serde_json::Value,
    mode: ApplyMode,
    guard: Option<&PathGuard>,
) -> anyhow::Result<EditResult> {
    let op = Operation::DocSet {
        path: path.to_string_lossy().into(),
        selector: selector.into(),
        value,
    };
    doc_write(op, path, mode, guard, "doc.set")
}

/// Delete a value at a selector path in a JSON, YAML, or TOML file.
pub fn doc_delete(
    path: &Path,
    selector: &str,
    mode: ApplyMode,
    guard: Option<&PathGuard>,
) -> anyhow::Result<EditResult> {
    let op = Operation::DocDelete {
        path: path.to_string_lossy().into(),
        selector: selector.into(),
    };
    doc_write(op, path, mode, guard, "doc.delete")
}

/// Deep-merge a value into a JSON, YAML, or TOML file.
///
/// When `selector` is [`None`], merges into the document root (single-document
/// files). For multi-document YAML (top-level array of documents), pass
/// `Some("0")` or `Some("[0]")` to merge into the first document without
/// replacing the whole stream. Merging a non-array overlay into a multi-doc
/// **root** returns [`crate::exit::TypeErrorError`] (peels to
/// [`crate::fallback::EditErrorKind::TypeError`]).
///
/// # Example
///
/// ```rust,no_run
/// use patchloom::api::{self, ApplyMode};
/// use std::path::Path;
///
/// // Root merge (single-doc JSON/YAML/TOML)
/// let _ = api::doc_merge(
///     Path::new("config.json"),
///     serde_json::json!({"debug": true}),
///     ApplyMode::Apply,
///     None,
///     None,
/// )?;
///
/// // Multi-doc YAML: merge into document 0 only
/// let _ = api::doc_merge(
///     Path::new("stream.yaml"),
///     serde_json::json!({"c": 3}),
///     ApplyMode::Apply,
///     None,
///     Some("0"),
/// )?;
/// # Ok::<(), anyhow::Error>(())
/// ```
pub fn doc_merge(
    path: &Path,
    value: serde_json::Value,
    mode: ApplyMode,
    guard: Option<&PathGuard>,
    selector: Option<&str>,
) -> anyhow::Result<EditResult> {
    let op = Operation::DocMerge {
        path: path.to_string_lossy().into(),
        selector: selector.map(|s| s.into()),
        value,
    };
    doc_write(op, path, mode, guard, "doc.merge")
}

/// Get a value at a selector path from a JSON, YAML, or TOML file.
///
/// This is a read-only operation; the `mode` parameter is ignored.
pub fn doc_get(path: &Path, selector: &str) -> anyhow::Result<serde_json::Value> {
    let value = load_doc_value(path)?;

    match query_get(&value, selector)? {
        QueryResult::NoMatch => Err(crate::exit::NoMatchError {
            msg: format!("selector '{}' matched nothing", selector),
        }
        .into()),
        QueryResult::Values(vals) if vals.len() == 1 => Ok(vals
            .into_iter()
            .next()
            .expect("len()==1 guarantees element")),
        QueryResult::Values(vals) => Ok(serde_json::Value::Array(vals)),
    }
}

/// Check whether a selector path exists in a JSON, YAML, or TOML file.
pub fn doc_has(path: &Path, selector: &str) -> anyhow::Result<bool> {
    let value = load_doc_value(path)?;
    query_has(&value, selector)
}

/// Append a value to an array at a selector path.
pub fn doc_append(
    path: &Path,
    selector: &str,
    value: serde_json::Value,
    mode: ApplyMode,
    guard: Option<&PathGuard>,
) -> anyhow::Result<EditResult> {
    let op = Operation::DocAppend {
        path: path.to_string_lossy().into(),
        selector: selector.into(),
        value,
    };
    doc_write(op, path, mode, guard, "doc.append")
}

/// Prepend a value to an array at a selector path.
pub fn doc_prepend(
    path: &Path,
    selector: &str,
    value: serde_json::Value,
    mode: ApplyMode,
    guard: Option<&PathGuard>,
) -> anyhow::Result<EditResult> {
    let op = Operation::DocPrepend {
        path: path.to_string_lossy().into(),
        selector: selector.into(),
        value,
    };
    doc_write(op, path, mode, guard, "doc.prepend")
}

/// Update all values matching a selector with a new value.
///
/// Returns an `EditResult`. The number of matches updated is reflected in
/// whether the content changed.
pub fn doc_update(
    path: &Path,
    selector: &str,
    value: serde_json::Value,
    mode: ApplyMode,
    guard: Option<&PathGuard>,
) -> anyhow::Result<EditResult> {
    let op = Operation::DocUpdate {
        path: path.to_string_lossy().into(),
        selector: selector.into(),
        value,
    };
    doc_write(op, path, mode, guard, "doc.update")
}

/// Ensure a value exists at a selector path; set it only if missing.
pub fn doc_ensure(
    path: &Path,
    selector: &str,
    value: serde_json::Value,
    mode: ApplyMode,
    guard: Option<&PathGuard>,
) -> anyhow::Result<EditResult> {
    let op = Operation::DocEnsure {
        path: path.to_string_lossy().into(),
        selector: selector.into(),
        value,
    };
    doc_write(op, path, mode, guard, "doc.ensure")
}

/// Delete array elements matching a predicate (e.g., `"name=old"`).
pub fn doc_delete_where(
    path: &Path,
    selector: &str,
    predicate: &str,
    mode: ApplyMode,
    guard: Option<&PathGuard>,
) -> anyhow::Result<EditResult> {
    let op = Operation::DocDeleteWhere {
        path: path.to_string_lossy().into(),
        selector: selector.into(),
        predicate: predicate.into(),
    };
    doc_write(op, path, mode, guard, "doc.delete_where")
}

/// Move a value from one selector path to another within the same file.
pub fn doc_move(
    path: &Path,
    from_selector: &str,
    to_selector: &str,
    mode: ApplyMode,
    guard: Option<&PathGuard>,
) -> anyhow::Result<EditResult> {
    let op = Operation::DocMove {
        path: path.to_string_lossy().into(),
        from: from_selector.into(),
        to: to_selector.into(),
    };
    doc_write(op, path, mode, guard, "doc.move")
}