/// What kind of error occurred.

pub kind: EditErrorKind,

/// Human-readable error message.

pub message: String,

/// A suggestion for how to fix the issue (if available).

pub suggestion: Option<String>,

/// Similar targets found in the file (for "did you mean?" hints).

pub similar_targets: Vec<String>,

fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {

write!(f, "{}: {}", self.kind, self.message)?;

if let Some(ref suggestion) = self.suggestion {

write!(f, " (suggestion: {suggestion})")?;

}

if !self.similar_targets.is_empty() {

write!(f, " [similar: {}]", self.similar_targets.join(", "))?;

}

Ok(())

}

/// The edit target matched multiple locations in the file.

AmbiguousTarget,

/// The edit target was not found in the file.

NoMatch,

/// The edit would produce invalid syntax.

SyntaxInvalid,

/// Another edit already modified this region (for batch operations).

ConflictingEdit,

/// The file could not be parsed.

ParseError,

/// Path rejected by workspace PathGuard (#1492).

GuardRejected,

/// Invalid arguments or options for the edit.

InvalidInput,

/// Wrong value type for a doc selector (multi-document YAML bare key,

/// navigate into array as object, etc.). CLI JSON uses `error_kind:

/// "type_error"`. Distinct from [`Self::InvalidInput`] so hosts can

/// recover with `0.key` / `[0].key` without scraping English (#1883).

TypeError,

/// I/O or other operational failure.

OperationFailed,

/// Post-write format/lint hook failed (`format_failed` / #1663).

/// Distinct from generic [`Self::OperationFailed`] so hosts can branch

/// without scraping English.

FormatFailed,

/// Create/rename destination already exists without force.

/// CLI JSON uses `error_kind: "already_exists"`. Distinct from

/// [`Self::InvalidInput`] (empty path, directory target) and content SoftSkip

/// ([`Self::Binary`] / [`Self::InvalidEncoding`]) so hosts can hint

/// `overwrite`/`force` without scraping English (#1947 / #1963).

/// Appended after [`Self::FormatFailed`] so 0.18.0 discriminants stay stable.

AlreadyExists,

/// Path not found (`std::io::ErrorKind::NotFound`). CLI JSON uses

/// `error_kind: "not_found"`. Distinct from generic [`Self::OperationFailed`]

/// so hosts can treat missing paths separately from other I/O failures.

NotFound,

/// Patch/apply produced merge conflict markers. CLI JSON uses

/// `error_kind: "conflicts"`. Distinct from [`Self::ConflictingEdit`]

/// (batch region overlap) and generic [`Self::OperationFailed`].

Conflicts,

/// Check/preview reported pending changes, or soft assert-count mismatch

/// (`error_kind: "changes_detected"`, exit 2). Distinct from

/// [`Self::OperationFailed`] so hosts can mirror CLI exit-2 semantics

/// without scraping English.

ChangesDetected,

/// Target contains NUL in the binary probe window (not agent-editable text).

/// CLI JSON uses `error_kind: "binary"`. Distinct from [`Self::InvalidInput`]

/// (empty path, directory target, empty pattern) so hosts can recover

/// overwrite/delete/rename without treating all invalid input as binary (#1963).

/// Appended after [`Self::ChangesDetected`] so 0.18/0.19 discriminants stay stable.

Binary,

/// Target is not valid UTF-8 (and not binary by NUL probe). CLI JSON uses

/// `error_kind: "invalid_encoding"`. Distinct from [`Self::Binary`] and

/// [`Self::InvalidInput`] (#1963).

InvalidEncoding,

/// Fuzzy match span is over-wide vs `old` under [`crate::api::FuzzySpanPolicy`]

/// (or the host refused via `ReplaceOptions::refuse_suspicious_fuzzy`).

/// CLI/library JSON uses `error_kind: "fuzzy_span_suspicious"` (#2005).

/// Appended after [`Self::InvalidEncoding`] so 0.20/0.21 discriminants stay

/// stable.

FuzzySpanSuspicious,

/// Tree-sitter parse hit the per-file deadline (`error_kind: "parse_timeout"`).

/// Distinct from [`Self::ParseError`] so hosts can retry or skip without

/// treating a timeout as a missing grammar (#2406). Append-only after

/// [`Self::FuzzySpanSuspicious`].

ParseTimeout,

fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {

match self {

EditErrorKind::AmbiguousTarget => write!(f, "ambiguous_target"),

EditErrorKind::NoMatch => write!(f, "no_match"),

EditErrorKind::SyntaxInvalid => write!(f, "syntax_invalid"),

EditErrorKind::ConflictingEdit => write!(f, "conflicting_edit"),

EditErrorKind::ParseError => write!(f, "parse_error"),

EditErrorKind::GuardRejected => write!(f, "guard_rejected"),

EditErrorKind::InvalidInput => write!(f, "invalid_input"),

EditErrorKind::TypeError => write!(f, "type_error"),

EditErrorKind::OperationFailed => write!(f, "operation_failed"),

EditErrorKind::FormatFailed => write!(f, "format_failed"),

EditErrorKind::AlreadyExists => write!(f, "already_exists"),

EditErrorKind::NotFound => write!(f, "not_found"),

EditErrorKind::Conflicts => write!(f, "conflicts"),

EditErrorKind::ChangesDetected => write!(f, "changes_detected"),

EditErrorKind::Binary => write!(f, "binary"),

EditErrorKind::InvalidEncoding => write!(f, "invalid_encoding"),

EditErrorKind::FuzzySpanSuspicious => write!(f, "fuzzy_span_suspicious"),

EditErrorKind::ParseTimeout => write!(f, "parse_timeout"),

}

}

/// Build a structured edit error.

pub fn new(kind: EditErrorKind, message: impl Into<String>) -> Self {

Self {

kind,

message: message.into(),

suggestion: None,

similar_targets: Vec::new(),

}

}

/// PathGuard rejection as an `anyhow` error (`edit_error_kind` → [`EditErrorKind::GuardRejected`]).

///

/// Prefer this over [`crate::exit::InvalidInputError`] for guard failures so

/// library hosts and CLI JSON can branch on `guard_rejected` without scraping

/// English (#1935 / engine PathGuard paths).

pub fn guard_rejected(detail: impl std::fmt::Display) -> anyhow::Error {

Self::new(

EditErrorKind::GuardRejected,

format!("path rejected by workspace guard: {detail}"),

)

.into()

}

/// Attach similar-target suggestions (did-you-mean).

pub fn with_similar(mut self, similar: Vec<String>) -> Self {

self.similar_targets = similar;

self

}

/// Attach a single suggestion string.

pub fn with_suggestion(mut self, suggestion: impl Into<String>) -> Self {

self.suggestion = Some(suggestion.into());

self

}

for cause in err.chain() {

if let Some(kind) = classify_error(cause) {

return Some(kind);

}

}

None

for cause in err.chain() {

if let Some(e) = classify_error_ref(cause) {

return Some(e);

}

}

None

let mut current: Option<&(dyn std::error::Error + 'static)> = Some(err);

while let Some(e) = current {

if let Some(edit) = e.downcast_ref::<EditError>() {

return Some(edit.kind);

}

if e.downcast_ref::<crate::exit::NoMatchError>().is_some() {

return Some(EditErrorKind::NoMatch);

}

if e.downcast_ref::<crate::exit::AmbiguousError>().is_some() {

return Some(EditErrorKind::AmbiguousTarget);

}

if e.downcast_ref::<crate::exit::InvalidInputError>().is_some()

|| e.downcast_ref::<crate::exit::InvalidInputHintError>()

.is_some()

{

return Some(EditErrorKind::InvalidInput);

}

if e.downcast_ref::<crate::exit::AlreadyExistsError>()

.is_some()

{

return Some(EditErrorKind::AlreadyExists);

}

if e.downcast_ref::<crate::exit::TypeErrorError>().is_some() {

return Some(EditErrorKind::TypeError);

}

if e.downcast_ref::<crate::exit::ParseErrorError>().is_some() {

return Some(EditErrorKind::ParseError);

}

if e.downcast_ref::<crate::exit::ParseTimeoutError>().is_some() {

return Some(EditErrorKind::ParseTimeout);

}

if e.downcast_ref::<crate::exit::FormatFailedError>().is_some() {

return Some(EditErrorKind::FormatFailed);

}

if e.downcast_ref::<crate::exit::ConflictsError>().is_some() {

return Some(EditErrorKind::Conflicts);

}

if e.downcast_ref::<crate::exit::ChangesDetectedError>()

.is_some()

{

return Some(EditErrorKind::ChangesDetected);

}

if e.downcast_ref::<crate::exit::BinaryError>().is_some() {

return Some(EditErrorKind::Binary);

}

if e.downcast_ref::<crate::exit::InvalidEncodingError>()

.is_some()

{

return Some(EditErrorKind::InvalidEncoding);

}

if e.downcast_ref::<std::io::Error>()

.is_some_and(|io| io.kind() == std::io::ErrorKind::NotFound)

{

return Some(EditErrorKind::NotFound);

}

current = e.source();

}

None

/// CLI-stable kind string (`already_exists`, `binary`, …).

pub kind_str: &'static str,

/// Agent-facing message (same as CLI JSON `error` when possible).

pub message: String,

/// Optional suggestion from [`EditError`].

pub suggestion: Option<String>,

/// Similar targets from [`EditError`] (did-you-mean).

pub similar_targets: Vec<String>,

let kind_str = error_kind_str(err)?;

let (suggestion, similar_targets) = match edit_error_ref(err) {

Some(e) => (e.suggestion.clone(), e.similar_targets.clone()),

None => (None, Vec::new()),

};

Some(PeeledError {

kind_str,

message: crate::exit::agent_error_message(err),

suggestion,

similar_targets,

})

let mut current: Option<&'a (dyn std::error::Error + 'static)> = Some(err);

while let Some(e) = current {

if let Some(edit) = e.downcast_ref::<EditError>() {

return Some(edit);

}

current = e.source();

}

None

/// Whether the edit produces valid output.

pub valid: bool,

/// Syntax errors found (if invalid).

pub errors: Vec<String>,

/// Suspicious but technically valid issues.

pub warnings: Vec<String>,

content: &str,

from: &str,

to: &str,

file_path: Option<&str>,

) -> ValidationResult {

validate_edit_nth(content, from, to, file_path, None)

content: &str,

from: &str,

to: &str,

file_path: Option<&str>,

nth: Option<usize>,

) -> ValidationResult {

if from.is_empty() {

return ValidationResult {

valid: false,

errors: vec!["empty search pattern".into()],

warnings: vec![],

};

}

if !content.contains(from) {

return ValidationResult {

valid: false,

errors: vec![format!(

"pattern '{}' not found in content",

truncate_str(from, 60)

)],

warnings: vec![],

};

}

let new_content = match nth {

Some(0) => {

return ValidationResult {

valid: false,

errors: vec!["nth must be >= 1 (1-based indexing)".into()],

warnings: vec![],

};

}

Some(n) => {

// Replace only the Nth (1-based) occurrence.

let mut count = 0usize;

let mut result = String::with_capacity(content.len());

let mut remaining = content;

while let Some(pos) = remaining.find(from) {

count += 1;

if count == n {

result.push_str(&remaining[..pos]);

result.push_str(to);

result.push_str(&remaining[pos + from.len()..]);

break;

}

result.push_str(&remaining[..pos + from.len()]);

remaining = &remaining[pos + from.len()..];

}

if count < n {

return ValidationResult {

valid: false,

errors: vec![format!(

"occurrence {n} not found (only {count} occurrence{} exist{})",

if count == 1 { "" } else { "s" },

if count == 1 { "s" } else { "" },

)],

warnings: vec![],

};

}

result

}

None => content.replace(from, to),

};

let mut errors = Vec::new();

let mut warnings = Vec::new();

// If we can detect the file format, validate the result.

if let Some(path) = file_path

&& let Ok(fmt) = crate::ops::doc::detect_format(path)

{

let parse_err = match fmt {

crate::ops::doc::FileFormat::Json => {

crate::ops::doc::parse_doc(&new_content, &crate::ops::doc::FileFormat::Json)

.err()

.map(|e| format!("result would be invalid JSON: {e}"))

}

crate::ops::doc::FileFormat::Yaml => {

serde_yaml_ng::from_str::<serde_json::Value>(&new_content)

.err()

.map(|e| format!("result would be invalid YAML: {e}"))

}

crate::ops::doc::FileFormat::Toml => {

toml_edit::de::from_str::<serde_json::Value>(&new_content)

.err()

.map(|e| format!("result would be invalid TOML: {e}"))

}

crate::ops::doc::FileFormat::Env

| crate::ops::doc::FileFormat::Ini

| crate::ops::doc::FileFormat::Properties => {

crate::ops::doc::parse_doc(&new_content, &fmt)

.err()

.map(|e| format!("result would be invalid document: {e}"))

}

};

if let Some(msg) = parse_err {

errors.push(msg);

}

}

// Warn if the replacement creates unbalanced brackets/braces.

let open_parens =

new_content.matches('(').count() as i64 - new_content.matches(')').count() as i64;

let open_braces =

new_content.matches('{').count() as i64 - new_content.matches('}').count() as i64;

let open_brackets =

new_content.matches('[').count() as i64 - new_content.matches(']').count() as i64;

if open_parens != 0 {

warnings.push(format!("unbalanced parentheses (delta: {open_parens})"));

}

if open_braces != 0 {

warnings.push(format!("unbalanced braces (delta: {open_braces})"));

}

if open_brackets != 0 {

warnings.push(format!("unbalanced brackets (delta: {open_brackets})"));

}

ValidationResult {

valid: errors.is_empty(),

errors,

warnings,

}

let (ca, ta) = (candidate.len(), target.len());

if ca == 0 || ta == 0 {

return false;

}

let (shorter, longer) = if ca < ta { (ca, ta) } else { (ta, ca) };

// Allow ~2x length difference, or a small absolute gap for short ids.

shorter.saturating_mul(2) >= longer || longer - shorter <= 3

candidates: I,

target: &str,

max_results: usize,

) -> Vec<String>

I: IntoIterator<Item = &'a str>,

if target.is_empty() || max_results == 0 {

return vec![];

}

let mut scored: Vec<(String, f64)> = Vec::new();

let mut seen = std::collections::HashSet::new();

for candidate in candidates {

if candidate.is_empty() || candidate == target || !seen.insert(candidate) {

continue;

}

if !similar_target_length_plausible(candidate, target) {

continue;

}

let score = strsim::jaro_winkler(candidate, target);

if score > SIMILAR_TARGET_MIN_SCORE {

scored.push((candidate.to_string(), score));

}

}

scored.sort_by(|a, b| b.1.partial_cmp(&a.1).unwrap_or(std::cmp::Ordering::Equal));

scored.truncate(max_results);

scored.into_iter().map(|(s, _)| s).collect()

if target.is_empty() || content.is_empty() {

return vec![];

}

// Dedup before materializing: HashSet<&str> over borrowed slices so

// repeated identifiers do not each allocate a String (#2292).

let mut seen = std::collections::HashSet::new();

let mut tokens: Vec<&str> = Vec::new();

for line in content.lines() {

for ident in extract_identifiers(line) {

if seen.insert(ident) {

tokens.push(ident);

}

}

}

// Also try matching against whole lines for multi-word patterns.

if target.contains(' ') || target.len() > 20 {

for line in content.lines() {

let trimmed = line.trim();

if !trimmed.is_empty() && seen.insert(trimmed) {

tokens.push(trimmed);

}

}

}

find_similar_among(tokens, target, max_results)

content: &str,

target: &str,

before_context: Option<&str>,

after_context: Option<&str>,

) -> Option<AnchorMatchResult> {

if target.is_empty() {

return None;

}

// If exact match exists, return it directly.

if let Some(pos) = content.find(target) {

return Some(AnchorMatchResult {

matched_text: target.to_string(),

start_offset: pos,

strategy: MatchStrategy::Exact,

score: None,

});

}

// Try anchor-based matching using before/after context.

let lines: Vec<&str> = content.lines().collect();

let target_lines: Vec<&str> = target.lines().collect();

// Compute byte offset of each line start for accurate slicing,

// avoiding CRLF vs LF mismatch (the old code used a global

// heuristic that broke on mixed or CRLF line endings).

let mut line_byte_starts: Vec<usize> = vec![0];

for (i, b) in content.bytes().enumerate() {

if b == b'\n' {

line_byte_starts.push(i + 1);

}

}

if target_lines.is_empty() {

return None;

}

let first_target = target_lines[0].trim();

let last_target = target_lines.last().map(|l| l.trim()).unwrap_or("");

// Anchor matching requires at least one piece of structural context

// (before_context or after_context). Without context, it would

// degenerate into the same Jaro-Winkler line scan that the

// similarity path already does, making the fallback chain redundant.

if before_context.is_none() && after_context.is_none() {

return None;

}

// Find candidate positions by matching the first line with anchors.

for (i, line) in lines.iter().enumerate() {

let trimmed = line.trim();

// Check if this line is similar to the first target line.

if strsim::jaro_winkler(trimmed, first_target) < 0.85 {

continue;

}

// For multi-line targets, also verify the last line of the

// candidate region is similar to the last target line.

if target_lines.len() > 1 {

let end_idx = i + target_lines.len();

if end_idx > lines.len() {

continue;

}

let candidate_last = lines[end_idx - 1].trim();

if strsim::jaro_winkler(candidate_last, last_target) < 0.85 {

continue;

}

}

// If we have before_context, verify the preceding line matches.

// For multi-line context, compare only the last line (the one

// immediately before the target region).

if let Some(before) = before_context {

if i == 0 {

continue;

}

let prev = lines[i - 1].trim();

let before_line = before.lines().last().unwrap_or(before).trim();

if strsim::jaro_winkler(prev, before_line) < 0.8 {

continue;

}

}

// If we have after_context, check the line after the candidate region.

// For multi-line context, compare only the first line (the one

// immediately after the target region).

if let Some(after) = after_context {

let end_idx = i + target_lines.len();

if end_idx >= lines.len() {

continue;

}

let next = lines[end_idx].trim();

let after_line = after.lines().next().unwrap_or(after).trim();

if strsim::jaro_winkler(next, after_line) < 0.8 {

continue;

}

}

// Found a match. Extract the matched region directly from the

// original content so line endings are preserved exactly.

let end_idx = (i + target_lines.len()).min(lines.len());

let start_offset = line_byte_starts[i];

let end_offset = if end_idx < line_byte_starts.len() {

line_byte_starts[end_idx]

} else {

content.len()

};

// Strip exactly one trailing line ending to match the format

// of exact-match results (which carry no trailing newline).

let slice = &content[start_offset..end_offset];

let matched_text = slice

.strip_suffix("\r\n")

.or_else(|| slice.strip_suffix('\n'))

.unwrap_or(slice)

.to_string();

return Some(AnchorMatchResult {

matched_text,

start_offset,

strategy: MatchStrategy::Anchor,

score: None,

});

}

None

/// The text that was matched.

pub matched_text: String,

/// Byte offset of the match start in the content.

pub start_offset: usize,

/// Which matching strategy succeeded.

pub strategy: MatchStrategy,

/// Similarity score when [`MatchStrategy::Similarity`] succeeded (#1662).

pub score: Option<f64>,

/// Exact literal match.

Exact,

/// Anchor-based matching using surrounding context.

Anchor,

/// Similarity-based fuzzy matching.

Similarity,

fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {

match self {

MatchStrategy::Exact => write!(f, "exact"),

MatchStrategy::Anchor => write!(f, "anchor"),

MatchStrategy::Similarity => write!(f, "similarity"),

}

}

content: &str,

target: &str,

before_context: Option<&str>,

after_context: Option<&str>,

) -> Result<AnchorMatchResult, EditError> {

resolve_with_fallback_skip_exact(content, target, before_context, after_context, false)

content: &str,

target: &str,

before_context: Option<&str>,

after_context: Option<&str>,

skip_exact: bool,

) -> Result<AnchorMatchResult, EditError> {

// Step 1: Exact match (unless caller already enforced a stricter exact path).

if !skip_exact && let Some(pos) = content.find(target) {

return Ok(AnchorMatchResult {

matched_text: target.to_string(),

start_offset: pos,