patchloom/api/

md.rs

//! Markdown section-aware operations for the public library API.
//!
//! Standard write functions delegate to the tx engine via `execute_as_edit_result`.
//! Special cases (md_move_section cross-file, md_dedupe_headings with extra return
//! data) keep direct implementations with feature-gated tx fallbacks.

use std::path::Path;

use crate::containment::PathGuard;
use crate::ops;
use crate::plan::Operation;

use super::{ApplyMode, EditResult};

/// Unified write path for standard md operations.
#[cfg(any(feature = "cli", feature = "files"))]
fn md_write(
    op: Operation,
    path: &Path,
    mode: ApplyMode,
    guard: Option<&PathGuard>,
    action: &'static str,
) -> anyhow::Result<EditResult> {
    let abs = super::library_abs_path(path, guard)?;
    let mut op = op;
    rewrite_md_op_path(&mut op, &super::library_op_path(path, &abs, guard));
    let display = path.to_string_lossy();
    super::execute_as_edit_result_with_path(
        op,
        mode,
        super::library_project_root(&abs, guard),
        guard,
        action,
        None,
        Some(display.as_ref()),
    )
}

#[cfg(any(feature = "cli", feature = "files"))]
fn rewrite_md_op_path(op: &mut Operation, dest: &str) {
    match op {
        Operation::MdReplaceSection { path, .. }
        | Operation::MdInsertAfterHeading { path, .. }
        | Operation::MdInsertAfterSection { path, .. }
        | Operation::MdInsertBeforeHeading { path, .. }
        | Operation::MdUpsertBullet { path, .. }
        | Operation::MdTableAppend { path, .. }
        | Operation::MdMoveSection { path, .. }
        | Operation::MdDedupeHeadings { path, .. }
        | Operation::MdLintAgents { path, .. } => {
            *path = dest.into();
        }
        _ => {}
    }
}

#[cfg(not(any(feature = "cli", feature = "files")))]
fn md_write(
    _op: Operation,
    path: &Path,
    mode: ApplyMode,
    guard: Option<&PathGuard>,
    action: &'static str,
) -> anyhow::Result<EditResult> {
    // Fallback: execute the md operation through the tx engine's execute
    // path. Without the tx module, delegate to the ops layer directly.
    use crate::write::WritePolicy;

    // Re-extract the operation fields to call ops directly.
    // This is only used when building without cli/files features.
    let display = path.to_string_lossy();
    let path_owned = super::library_abs_path(path, guard)?;
    let path = path_owned.as_path();
    let path_str = display;
    let original = crate::files::load_text_strict(path, &path_str)?;

    let new_content = match _op {
        Operation::MdReplaceSection {
            heading, content, ..
        } => ops::md::replace_section_in(&original, &heading, &content)
            .map_err(|e| e.into_anyhow(&heading))?,
        Operation::MdInsertAfterHeading {
            heading, content, ..
        } => ops::md::insert_after_heading_in(&original, &heading, &content)
            .map_err(|e| e.into_anyhow(&heading))?,
        Operation::MdInsertAfterSection {
            heading, content, ..
        } => ops::md::insert_after_section_in(&original, &heading, &content)
            .map_err(|e| e.into_anyhow(&heading))?,
        Operation::MdInsertBeforeHeading {
            heading, content, ..
        } => ops::md::insert_before_heading_in(&original, &heading, &content)
            .map_err(|e| e.into_anyhow(&heading))?,
        Operation::MdUpsertBullet {
            heading, bullet, ..
        } => ops::md::upsert_bullet_in(&original, &heading, &bullet)
            .map_err(|e| e.into_anyhow(&heading))?,
        Operation::MdTableAppend { heading, row, .. } => {
            let (body_start, body_end) =
                ops::md::find_section(&original, &heading).map_err(|e| e.into_anyhow(&heading))?;
            return match ops::md::table_append_in(&original, body_start, body_end, &row) {
                Ok(new_content) => {
                    let policy = WritePolicy::default();
                    let (applied, backup_session) =
                        super::write_if_apply(path, &new_content, mode, &policy, guard)?;
                    let mut edit = super::build_edit_result(
                        &path_str,
                        original,
                        new_content,
                        applied,
                        action,
                        None,
                    );
                    edit.backup_session = backup_session;
                    Ok(edit)
                }
                Err(e) => Err(anyhow::Error::new(crate::exit::InvalidInputError {
                    msg: format!("{e} under heading {heading:?} in {path_str}"),
                })),
            };
        }
        _ => {
            return Err(anyhow::Error::new(crate::exit::InvalidInputError {
                msg: format!("unsupported md operation in no-cli path for {path_str}"),
            }));
        }
    };

    let policy = WritePolicy::default();
    let (applied, backup_session) =
        super::write_if_apply(path, &new_content, mode, &policy, guard)?;
    let mut edit =
        super::build_edit_result(&path_str, original, new_content, applied, action, None);
    edit.backup_session = backup_session;
    Ok(edit)
}

/// Replace the body of a markdown section identified by heading.
pub fn md_replace_section(
    path: &Path,
    heading: &str,
    content: &str,
    mode: ApplyMode,
    guard: Option<&PathGuard>,
) -> anyhow::Result<EditResult> {
    let op = Operation::MdReplaceSection {
        path: path.to_string_lossy().into(),
        heading: heading.into(),
        content: content.into(),
    };
    md_write(op, path, mode, guard, "md.replace_section")
}

/// Insert or update a bullet point under a markdown heading.
///
/// If the bullet already exists (exact match), the file is unchanged.
pub fn md_upsert_bullet(
    path: &Path,
    heading: &str,
    bullet: &str,
    mode: ApplyMode,
    guard: Option<&PathGuard>,
) -> anyhow::Result<EditResult> {
    let op = Operation::MdUpsertBullet {
        path: path.to_string_lossy().into(),
        heading: heading.into(),
        bullet: bullet.into(),
    };
    md_write(op, path, mode, guard, "md.upsert_bullet")
}

/// Append a row to a markdown table under a heading.
pub fn md_table_append(
    path: &Path,
    heading: &str,
    row: &str,
    mode: ApplyMode,
    guard: Option<&PathGuard>,
) -> anyhow::Result<EditResult> {
    let op = Operation::MdTableAppend {
        path: path.to_string_lossy().into(),
        heading: heading.into(),
        row: row.into(),
    };
    md_write(op, path, mode, guard, "md.table_append")
}

/// Insert content after a markdown heading.
pub fn md_insert_after_heading(
    path: &Path,
    heading: &str,
    insertion: &str,
    mode: ApplyMode,
    guard: Option<&PathGuard>,
) -> anyhow::Result<EditResult> {
    let op = Operation::MdInsertAfterHeading {
        path: path.to_string_lossy().into(),
        heading: heading.into(),
        content: insertion.into(),
    };
    md_write(op, path, mode, guard, "md.insert_after_heading")
}

/// Insert content after the full section body (sibling placement). #1726
pub fn md_insert_after_section(
    path: &Path,
    heading: &str,
    insertion: &str,
    mode: ApplyMode,
    guard: Option<&PathGuard>,
) -> anyhow::Result<EditResult> {
    let op = Operation::MdInsertAfterSection {
        path: path.to_string_lossy().into(),
        heading: heading.into(),
        content: insertion.into(),
    };
    md_write(op, path, mode, guard, "md.insert_after_section")
}

/// Move a markdown section to a position relative to another heading.
///
/// For same-file moves, pass `to` as `None`. For cross-file moves, pass the
/// destination file path in `to`.
///
/// Cross-file moves are complex (two files, guard on dest) and retain the
/// direct implementation. Same-file moves route through the tx engine when
/// available.
pub fn md_move_section(
    path: &Path,
    heading: &str,
    position: (&str, &str),
    to: Option<&Path>,
    mode: ApplyMode,
    guard: Option<&PathGuard>,
) -> anyhow::Result<EditResult> {
    // Cross-file moves retain the direct implementation because the tx engine
    // only handles single-file operations. Same-file moves can route through
    // the engine but cross-file needs coordinated writes to two files.
    let display = path.to_string_lossy().into_owned();
    let path_owned = super::library_abs_path(path, guard)?;
    let dest_owned = match to {
        Some(dest_path) => Some(super::library_abs_path(dest_path, guard)?),
        None => None,
    };
    let path = path_owned.as_path();
    let to = dest_owned.as_deref();
    let path_str = display;
    let original = crate::files::load_text_strict(path, &path_str)?;

    let dest_content = match to {
        Some(dest_path) => {
            let d = dest_path.to_string_lossy();
            crate::files::load_text_strict(dest_path, &d)?
        }
        None => original.clone(),
    };

    let (new_source, new_dest) =
        ops::md::move_section_in(&original, heading, &dest_content, position, to.is_none())
            .map_err(|e| e.into_anyhow(heading, position.1))?;

    let policy = crate::write::WritePolicy::default();
    let dest = to.map(|p| p.to_string_lossy().to_string());

    // Cross-file: one backup session covering source + dest (all-or-nothing).
    // Same-file: single write path.
    let (applied, backup_session) = if let Some(dest_path) = to {
        let backup_root = super::library_project_root(path, guard);
        let files: [(&Path, &str); 2] =
            [(dest_path, new_dest.as_str()), (path, new_source.as_str())];
        super::write_if_apply_many(&files, mode, &policy, guard, backup_root)?
    } else {
        super::write_if_apply(path, &new_source, mode, &policy, guard)?
    };

    let mut edit =
        super::build_edit_result(&path_str, original, new_source, applied, "md.move", dest);
    edit.backup_session = backup_session;
    Ok(edit)
}

/// Remove duplicate headings at the same level in a markdown file.
///
/// Returns the `EditResult` and a list of removed duplicate heading texts.
/// Retains direct implementation because the removed-headings list is not
/// available from the tx engine output.
pub fn md_dedupe_headings(
    path: &Path,
    mode: ApplyMode,
    guard: Option<&PathGuard>,
) -> anyhow::Result<(EditResult, Vec<String>)> {
    let display = path.to_string_lossy();
    let path_owned = super::library_abs_path(path, guard)?;
    let path = path_owned.as_path();
    let path_str = display;
    let original = crate::files::load_text_strict(path, &path_str)?;

    let (new_content, removed) = ops::md::dedupe_headings_in(&original);

    let policy = crate::write::WritePolicy::default();
    let (applied, backup_session) =
        super::write_if_apply(path, &new_content, mode, &policy, guard)?;
    let mut edit =
        super::build_edit_result(&path_str, original, new_content, applied, "md.dedupe", None);
    edit.backup_session = backup_session;
    Ok((edit, removed))
}

/// A lint issue found in a markdown file.
///
/// Re-exported from `ops::md` so library consumers don't need to import
/// from the internal `cmd` module path.
pub use crate::ops::md::LintIssue;

/// Lint a markdown file for common agent-rules issues (duplicate headings,
/// missing sections, etc.).
///
/// Returns a list of lint issues found. This is a read-only operation.
pub fn md_lint_agents(path: &Path) -> anyhow::Result<Vec<LintIssue>> {
    let display = path.to_string_lossy();
    let content = crate::files::load_text_strict(path, &display)?;
    Ok(crate::ops::md::lint_agents_content(&content))
}

/// Insert content before a markdown heading.
pub fn md_insert_before_heading(
    path: &Path,
    heading: &str,
    insertion: &str,
    mode: ApplyMode,
    guard: Option<&PathGuard>,
) -> anyhow::Result<EditResult> {
    let op = Operation::MdInsertBeforeHeading {
        path: path.to_string_lossy().into(),
        heading: heading.into(),
        content: insertion.into(),
    };
    md_write(op, path, mode, guard, "md.insert_before_heading")
}