perl_lsp/util/

mod.rs

//! Text processing utilities for LSP
//!
//! Common text processing helpers used across the LSP implementation.
//! Includes panic-free accessors for safe string processing.

pub mod command_timeout;
pub mod uri;

pub use command_timeout::run_command_with_timeout;

use std::io;
use std::path::Path;

use lsp_types::Position;
use perl_module::reference::extract_module_reference as extract_module_reference_at_cursor;
use perl_module::reference::extract_module_reference_extended as extract_module_reference_extended_at_cursor;

// Re-export engine utilities
pub use perl_parser::util::{code_slice, find_data_marker_byte_lexed};
pub use perl_symbol::cursor::{
    byte_offset_utf16, is_modchar, is_word_boundary, token_under_cursor,
};

// =============================================================================
// Panic-free character accessors (Issue #143)
// =============================================================================

/// Safely get the first character of a string slice.
/// Returns None for empty strings instead of panicking.
#[inline]
pub fn first_char(s: &str) -> Option<char> {
    s.chars().next()
}

/// Safely get the nth character of a string slice.
/// Returns None if index is out of bounds instead of panicking.
#[inline]
pub fn nth_char(s: &str, n: usize) -> Option<char> {
    s.chars().nth(n)
}

/// Safely get the first character as a String.
/// Useful when you need the sigil character as a string.
#[inline]
pub fn first_char_string(s: &str) -> Option<String> {
    s.chars().next().map(|c| c.to_string())
}

/// Safely check if the first character satisfies a predicate.
/// Returns false for empty strings.
#[inline]
pub fn first_char_is<F: FnOnce(char) -> bool>(s: &str, predicate: F) -> bool {
    s.chars().next().is_some_and(predicate)
}

/// Safely check if the nth character satisfies a predicate.
/// Returns false if index is out of bounds.
#[inline]
pub fn nth_char_is<F: FnOnce(char) -> bool>(s: &str, n: usize, predicate: F) -> bool {
    s.chars().nth(n).is_some_and(predicate)
}

/// Escape special markdown characters in plain text to prevent unintended formatting.
///
/// Escapes: backtick (`), hash (#), asterisk (*), underscore (_), brackets ([, ]),
/// and other markdown formatting characters so they render as literal text in hover cards.
///
/// This preserves the semantic content of comments and documentation while preventing
/// markdown special characters from being interpreted as formatting directives.
///
/// # Examples
///
/// ```ignore
/// assert_eq!(escape_markdown_text("*bold*"), "\\*bold\\*");
/// assert_eq!(escape_markdown_text("[link]"), "\\[link\\]");
/// assert_eq!(escape_markdown_text("code`here"), "code\\`here");
/// ```
pub fn escape_markdown_text(text: &str) -> String {
    let mut result = String::with_capacity(text.len());
    for ch in text.chars() {
        match ch {
            '`' | '#' | '*' | '_' | '[' | ']' | '\\' | '|' | '-' => {
                result.push('\\');
                result.push(ch);
            }
            _ => result.push(ch),
        }
    }
    result
}

/// Decode source text bytes while handling common editor encodings.
///
/// Behavior:
/// - UTF-8 with optional BOM
/// - UTF-16 LE/BE when BOM is present (odd-length payloads fall back to
///   Latin-1 decoding of the original bytes rather than silently
///   truncating the trailing byte)
/// - Latin-1 byte-preserving fallback for non-UTF8 legacy files
pub fn decode_text_bytes(bytes: &[u8]) -> String {
    if bytes.starts_with(&[0xEF, 0xBB, 0xBF]) {
        if let Ok(utf8) = std::str::from_utf8(&bytes[3..]) {
            return utf8.to_string();
        }
    }

    if bytes.starts_with(&[0xFF, 0xFE]) {
        if let Some(decoded) = decode_utf16_lossy(&bytes[2..], true) {
            return decoded;
        }
        // Odd-length UTF-16 payload — fall through to latin-1 on the full bytes.
    }

    if bytes.starts_with(&[0xFE, 0xFF]) {
        if let Some(decoded) = decode_utf16_lossy(&bytes[2..], false) {
            return decoded;
        }
        // Odd-length UTF-16 payload — fall through to latin-1 on the full bytes.
    }

    match std::str::from_utf8(bytes) {
        Ok(utf8) => utf8.to_string(),
        Err(_) => bytes.iter().map(|byte| char::from(*byte)).collect(),
    }
}

/// Read a text file and decode it with [`decode_text_bytes`].
pub fn read_text_file_with_encoding(path: &Path) -> io::Result<String> {
    std::fs::read(path).map(|bytes| decode_text_bytes(&bytes))
}

/// Decode a UTF-16 byte payload (BOM already stripped) into a String.
///
/// Returns `None` when the payload has an odd byte length, since UTF-16
/// code units are always 2 bytes and a dangling odd byte indicates
/// corrupted or mis-detected input. Callers should fall back to another
/// decoder in that case rather than silently truncating the trailing byte.
fn decode_utf16_lossy(bytes: &[u8], little_endian: bool) -> Option<String> {
    if !bytes.len().is_multiple_of(2) {
        return None;
    }
    let mut words = Vec::with_capacity(bytes.len() / 2);
    for pair in bytes.chunks_exact(2) {
        let word = if little_endian {
            u16::from_le_bytes([pair[0], pair[1]])
        } else {
            u16::from_be_bytes([pair[0], pair[1]])
        };
        words.push(word);
    }
    Some(String::from_utf16_lossy(&words))
}

/// Convert byte offset to UTF-16 column position
///
/// LSP uses UTF-16 code units for character positions, but Rust strings use
/// UTF-8 byte offsets. This function converts a byte position within a line
/// to the corresponding UTF-16 column position.
pub fn byte_to_utf16_col(line_text: &str, byte_pos: usize) -> usize {
    let mut units = 0;
    for (i, ch) in line_text.char_indices() {
        if i >= byte_pos {
            break;
        }
        // UTF-16 encoding: chars >= U+10000 use 2 units
        units += if ch as u32 >= 0x10000 { 2 } else { 1 };
    }
    units
}

/// Convert byte offset to line and column
pub fn byte_to_line_col(source: &str, offset: usize) -> (u32, u32) {
    let mut line = 0;
    let mut col = 0;

    for (i, ch) in source.char_indices() {
        if i >= offset {
            break;
        }
        if ch == '\n' {
            line += 1;
            col = 0;
        } else {
            col += 1;
        }
    }

    (line, col)
}

/// Find matching closing parenthesis
pub fn find_matching_paren(s: &str, open_at: usize) -> Option<usize> {
    // s[open_at] must be '('; walk forwards tracking () and quotes.
    let mut i = open_at;
    let mut depth_par = 0i32;
    let mut in_s = false;
    let mut in_d = false;
    while i < s.len() {
        let b = s.as_bytes()[i];
        let prev_backslash = i > 0 && s.as_bytes()[i - 1] == b'\\';
        if in_s {
            if b == b'\'' && !prev_backslash {
                in_s = false;
            }
        } else if in_d {
            if b == b'"' && !prev_backslash {
                in_d = false;
            }
        } else {
            match b {
                b'\'' => in_s = true,
                b'"' => in_d = true,
                b'(' => depth_par += 1,
                b')' => {
                    depth_par -= 1;
                    if depth_par == 0 {
                        return Some(i);
                    }
                }
                _ => {}
            }
        }
        i += 1;
    }
    None
}

/// Scan forward until end of statement (top-level `;`) honoring quotes/brackets.
pub fn slice_until_stmt_end(src: &str, from: usize) -> usize {
    let mut i = from;
    let mut depth_par = 0i32;
    let mut depth_brk = 0i32;
    let mut depth_brc = 0i32;
    let mut in_s = false;
    let mut in_d = false;
    while i < src.len() {
        let b = src.as_bytes()[i];
        let esc = i > 0 && src.as_bytes()[i - 1] == b'\\';
        if in_s {
            if b == b'\'' && !esc {
                in_s = false;
            }
        } else if in_d {
            if b == b'"' && !esc {
                in_d = false;
            }
        } else {
            match b {
                b'\'' => in_s = true,
                b'"' => in_d = true,
                b'(' => depth_par += 1,
                b')' => depth_par -= 1,
                b'[' => depth_brk += 1,
                b']' => depth_brk -= 1,
                b'{' => depth_brc += 1,
                b'}' => depth_brc -= 1,
                b';' if depth_par == 0 && depth_brk == 0 && depth_brc == 0 => return i,
                _ => {}
            }
        }
        i += 1;
    }
    src.len()
}

/// Top-level argument starts for a comma-separated list without surrounding parens.
pub fn arg_starts_top_level(src: &str) -> Vec<usize> {
    let mut v = Vec::new();
    let mut i = 0usize;
    while i < src.len() && src.as_bytes()[i].is_ascii_whitespace() {
        i += 1;
    }
    if i < src.len() {
        v.push(i);
    }
    let mut j = i;
    let mut depth_par = 0i32;
    let mut depth_brk = 0i32;
    let mut depth_brc = 0i32;
    let mut in_s = false;
    let mut in_d = false;
    while j < src.len() {
        let b = src.as_bytes()[j];
        let esc = j > 0 && src.as_bytes()[j - 1] == b'\\';
        if in_s {
            if b == b'\'' && !esc {
                in_s = false;
            }
        } else if in_d {
            if b == b'"' && !esc {
                in_d = false;
            }
        } else {
            match b {
                b'\'' => in_s = true,
                b'"' => in_d = true,
                b'(' => depth_par += 1,
                b')' => depth_par -= 1,
                b'[' => depth_brk += 1,
                b']' => depth_brk -= 1,
                b'{' => depth_brc += 1,
                b'}' => depth_brc -= 1,
                b',' if depth_par == 0 && depth_brk == 0 && depth_brc == 0 => {
                    let mut k = j + 1;
                    while k < src.len() && src.as_bytes()[k].is_ascii_whitespace() {
                        k += 1;
                    }
                    if k < src.len() {
                        v.push(k);
                    }
                }
                _ => {}
            }
        }
        j += 1;
    }
    v
}

/// Move the anchor inside an argument to the "interesting" token:
///  - skip leading whitespace
///  - for `my|our` args, jump to the first sigiled var (`$foo`/`@a`/`%h`)
///  - for bareword filehandles (e.g., `FH`), jump to the bareword
pub fn anchor_arg_start(body: &str, rel: usize) -> usize {
    let s = &body[rel..];
    let mut i = 0usize;
    while i < s.len() && s.as_bytes()[i].is_ascii_whitespace() {
        i += 1;
    }
    // my/our <sigiled-var>
    if s[i..].starts_with("my ") || s[i..].starts_with("our ") {
        let mut j = i + 3; // skip "my " / "our "
        while j < s.len() && s.as_bytes()[j].is_ascii_whitespace() {
            j += 1;
        }
        return rel + j;
    }
    // If next is sigiled variable, keep; else keep bareword start
    rel + i
}

/// If argument starts at `my $fh`, retarget anchor to the `$fh` (or bareword FH).
pub fn smart_arg_anchor(body: &str, rel: usize) -> usize {
    let s = &body[rel..];
    let mut i = 0usize;
    while i < s.len() && s.as_bytes()[i].is_ascii_whitespace() {
        i += 1;
    }

    // handle my/our
    for kw in ["my ", "our "] {
        if s[i..].starts_with(kw) {
            i += kw.len();
            while i < s.len() && s.as_bytes()[i].is_ascii_whitespace() {
                i += 1;
            }
            break;
        }
    }

    // valid anchors: sigils, barewords, deref braces and array/hash derefs
    // $, @, %, &, { (for @{ ... }, %{ ... }), [ (rare, but safe), or A-Za-z_ bareword
    let b = s.as_bytes().get(i).copied().unwrap_or(b' ');
    if matches!(b, b'$' | b'@' | b'%' | b'&' | b'{' | b'[') || b.is_ascii_alphabetic() || b == b'_'
    {
        return rel + i;
    }
    rel + i
}

/// Find argument starts in function call body
pub fn arg_starts_in_call_body(body: &str) -> Vec<usize> {
    // Return byte offsets (within body) where each top-level argument starts.
    let mut starts = Vec::new();
    let mut i = 0usize;
    let mut depth_par = 0i32;
    let mut depth_brk = 0i32;
    let mut depth_brc = 0i32;
    let mut in_s = false;
    let mut in_d = false;
    // First arg always starts at the first non-space
    while i < body.len() && body.as_bytes()[i].is_ascii_whitespace() {
        i += 1;
    }
    if i < body.len() {
        starts.push(i);
    }
    let mut j = i;
    while j < body.len() {
        let b = body.as_bytes()[j];
        let prev_backslash = j > 0 && body.as_bytes()[j - 1] == b'\\';
        if in_s {
            if b == b'\'' && !prev_backslash {
                in_s = false;
            }
        } else if in_d {
            if b == b'"' && !prev_backslash {
                in_d = false;
            }
        } else {
            match b {
                b'\'' => in_s = true,
                b'"' => in_d = true,
                b'(' => depth_par += 1,
                b')' => depth_par -= 1,
                b'[' => depth_brk += 1,
                b']' => depth_brk -= 1,
                b'{' => depth_brc += 1,
                b'}' => depth_brc -= 1,
                b',' if depth_par == 0 && depth_brk == 0 && depth_brc == 0 => {
                    // next arg start = first non-space after comma
                    let mut k = j + 1;
                    while k < body.len() && body.as_bytes()[k].is_ascii_whitespace() {
                        k += 1;
                    }
                    if k < body.len() {
                        starts.push(k);
                    }
                }
                _ => {}
            }
        }
        j += 1;
    }
    starts
}

/// Convert position to byte offset
pub fn pos_to_offset_bytes(text: &str, line: u32, ch: u32) -> usize {
    let mut byte = 0usize;
    for (cur, l) in text.split_inclusive('\n').enumerate() {
        if cur as u32 == line {
            return byte + (ch as usize).min(l.len());
        }
        byte += l.len();
    }
    text.len()
}

/// Slice text within range
pub fn slice_in_range(text: &str, start: (u32, u32), end: (u32, u32)) -> (usize, usize, &str) {
    let s = pos_to_offset_bytes(text, start.0, start.1);
    let e = pos_to_offset_bytes(text, end.0, end.1);
    let (s, e) = char_boundary_range(text, s, e);
    (s, e, &text[s..e])
}

/// Get text around an offset position
pub fn get_text_around_offset(content: &str, offset: usize, radius: usize) -> String {
    get_text_window_around_offset(content, offset, radius).1
}

/// Get text around an offset position and return the adjusted byte start.
pub fn get_text_window_around_offset(
    content: &str,
    offset: usize,
    radius: usize,
) -> (usize, String) {
    let offset = offset.min(content.len());
    let start = offset.saturating_sub(radius);
    let end = offset.saturating_add(radius).min(content.len());
    let (start, end) = char_boundary_range(content, start, end);
    (start, content[start..end].to_string())
}

fn char_boundary_range(text: &str, start: usize, end: usize) -> (usize, usize) {
    let start = start.min(text.len());
    let end = end.min(text.len());
    if start > end {
        let boundary = floor_char_boundary(text, end);
        return (boundary, boundary);
    }
    (floor_char_boundary(text, start), ceil_char_boundary(text, end))
}

fn floor_char_boundary(text: &str, index: usize) -> usize {
    let mut index = index.min(text.len());
    while index > 0 && !text.is_char_boundary(index) {
        index -= 1;
    }
    index
}

fn ceil_char_boundary(text: &str, index: usize) -> usize {
    let mut index = index.min(text.len());
    while index < text.len() && !text.is_char_boundary(index) {
        index += 1;
    }
    index
}

/// Extract module reference from text (e.g., from "use Module::Name" or "require Module::Name")
pub fn extract_module_reference(text: &str, cursor_pos: usize) -> Option<String> {
    extract_module_reference_at_cursor(text, cursor_pos)
}

/// Extract module reference including `use parent`/`use base` argument modules.
///
/// This extends [`extract_module_reference`] to also resolve quoted module names
/// inside `use parent 'Module::Name'` and `use base qw(Module::Name)` statements.
pub fn extract_module_reference_extended(text: &str, cursor_pos: usize) -> Option<String> {
    extract_module_reference_extended_at_cursor(text, cursor_pos)
}

/// Convert an LSP position to a byte offset in the text (UTF-16 aware, CRLF safe)
pub fn position_to_offset(content: &str, line: u32, character: u32) -> Option<usize> {
    let mut cur_line = 0u32;
    let mut col_utf16 = 0u32;
    let mut prev_was_cr = false;

    for (byte_idx, ch) in content.char_indices() {
        // Check if we've reached the target position
        if cur_line == line && col_utf16 == character {
            return Some(byte_idx);
        }

        // Handle line endings and character counting
        match ch {
            '\n' => {
                if !prev_was_cr {
                    // Standalone \n
                    cur_line += 1;
                    col_utf16 = 0;
                }
                // If prev_was_cr, this \n is part of CRLF and we already incremented the line
            }
            '\r' => {
                // Always increment line on \r (whether solo or part of CRLF)
                cur_line += 1;
                col_utf16 = 0;
            }
            _ => {
                // Regular character - only count UTF-16 units on target line
                if cur_line == line {
                    col_utf16 += if ch.len_utf16() == 2 { 2 } else { 1 };
                }
            }
        }

        prev_was_cr = ch == '\r';
    }

    // Handle end of file position
    if cur_line == line && col_utf16 == character {
        return Some(content.len());
    }

    // Return None if position is out of bounds
    None
}

/// Convert a byte offset to an LSP position (UTF-16 aware, CRLF safe)
pub fn offset_to_position(content: &str, offset: usize) -> Position {
    let mut line = 0u32;
    let mut col_utf16 = 0u32;
    let mut byte_pos = 0usize;
    let mut chars = content.chars().peekable();

    while let Some(ch) = chars.next() {
        if byte_pos >= offset {
            break;
        }

        match ch {
            '\r' => {
                // Peek ahead to see if this is CRLF
                if chars.peek() == Some(&'\n') {
                    // This is CRLF - treat as single line ending
                    if byte_pos + 1 >= offset {
                        // Offset is at the \r - treat as end of current line
                        break;
                    }
                    // Skip both \r and \n
                    chars.next(); // consume the \n
                    line += 1;
                    col_utf16 = 0;
                    byte_pos += 2; // \r + \n
                } else {
                    // Solo \r - treat as line ending
                    line += 1;
                    col_utf16 = 0;
                    byte_pos += ch.len_utf8();
                }
            }
            '\n' => {
                // LF (could be standalone or part of CRLF, but CRLF is handled above)
                line += 1;
                col_utf16 = 0;
                byte_pos += ch.len_utf8();
            }
            _ => {
                // Regular character
                col_utf16 += if ch.len_utf16() == 2 { 2 } else { 1 };
                byte_pos += ch.len_utf8();
            }
        }
    }

    Position { line, character: col_utf16 }
}

#[cfg(test)]
mod tests {
    use super::{
        arg_starts_in_call_body, arg_starts_top_level, byte_to_utf16_col, decode_text_bytes,
        escape_markdown_text, extract_module_reference, find_matching_paren,
        get_text_around_offset, get_text_window_around_offset, offset_to_position,
        position_to_offset, slice_in_range, slice_until_stmt_end, smart_arg_anchor,
    };
    use lsp_types::Position;

    #[test]
    fn extract_module_reference_detects_use_statement_token() {
        let line = "use Demo::Worker;";
        let cursor = line.find("Worker").unwrap_or(0);

        assert_eq!(extract_module_reference(line, cursor), Some("Demo::Worker".to_string()));
    }

    #[test]
    fn extract_module_reference_normalizes_legacy_separators() {
        let line = "require Demo'Worker;";
        let cursor = line.find("Worker").unwrap_or(0);

        assert_eq!(extract_module_reference(line, cursor), Some("Demo::Worker".to_string()));
    }

    #[test]
    fn find_matching_paren_ignores_parens_inside_quotes() {
        let text = r#"call("ignored ) token", nested(1, 2)) more"#;
        assert_eq!(find_matching_paren(text, 4), Some(36));
    }

    #[test]
    fn slice_until_stmt_end_skips_nested_structures() {
        let text = r#"my $x = foo(";", [1, 2], { k => ";" }); my $y = 1;"#;
        assert_eq!(slice_until_stmt_end(text, 0), 38);
    }

    #[test]
    fn arg_start_helpers_ignore_nested_commas() {
        let text = r#" $a, fn(1,2), {k=>3}, "x,y" "#;
        assert_eq!(arg_starts_top_level(text), vec![1, 5, 14, 22]);
        assert_eq!(arg_starts_in_call_body(text), vec![1, 5, 14, 22]);
    }

    #[test]
    fn smart_arg_anchor_skips_our_keyword() {
        let body = "our $fh, @rest";
        assert_eq!(smart_arg_anchor(body, 0), 4);
    }

    #[test]
    fn byte_to_utf16_col_counts_surrogate_pairs() {
        let line = "a😀z";
        assert_eq!(byte_to_utf16_col(line, 0), 0);
        assert_eq!(byte_to_utf16_col(line, 1), 1);
        assert_eq!(byte_to_utf16_col(line, 5), 3);
    }

    #[test]
    fn position_offset_roundtrip_handles_crlf_and_emoji() {
        let content = "my 😀\r\nnext";
        let pos_after_emoji = Position { line: 0, character: 5 };
        let offset = position_to_offset(content, pos_after_emoji.line, pos_after_emoji.character);
        assert_eq!(offset, Some(7));
        assert_eq!(offset_to_position(content, 7), pos_after_emoji);
    }

    #[test]
    fn get_text_around_offset_snaps_start_to_utf8_boundary() {
        let prefix = format!("{}{}\n", "🦀", "x".repeat(48));
        let content = format!("{prefix}sub foo {{}}");
        let offset = prefix.len();

        let text_around = get_text_around_offset(&content, offset, 50);

        assert!(text_around.starts_with("🦀"));
        assert!(text_around.contains("sub foo"));
    }

    #[test]
    fn get_text_window_around_offset_reports_adjusted_utf8_start() {
        let prefix = format!("{}{}\n", "🦀", "x".repeat(48));
        let content = format!("{prefix}sub foo {{}}");
        let offset = prefix.len();

        let (start, text_around) = get_text_window_around_offset(&content, offset, 50);
        let cursor_in_text = offset.saturating_sub(start);

        assert_eq!(start, 0);
        assert!(text_around.is_char_boundary(cursor_in_text));
        assert!(text_around[cursor_in_text..].starts_with("sub foo"));
    }

    #[test]
    fn slice_in_range_snaps_utf8_cut_points() {
        let text = "🦀abc";

        let (start, end, slice) = slice_in_range(text, (0, 2), (0, 3));

        assert_eq!(start, 0);
        assert_eq!(end, "🦀".len());
        assert_eq!(slice, "🦀");
    }

    #[test]
    fn slice_in_range_returns_empty_for_reversed_range() {
        let text = "🦀abc";

        let (start, end, slice) = slice_in_range(text, (0, 5), (0, 2));

        assert_eq!(start, 0);
        assert_eq!(end, 0);
        assert!(slice.is_empty());
    }

    #[test]
    fn decode_text_bytes_supports_utf16_le_bom() {
        let bytes = [0xFF, 0xFE, b'P', 0x00, b'e', 0x00, b'r', 0x00, b'l', 0x00];
        assert_eq!(decode_text_bytes(&bytes), "Perl");
    }

    #[test]
    fn decode_text_bytes_falls_back_to_latin1() {
        let bytes = [0x63, 0x61, 0x66, 0xE9];
        assert_eq!(decode_text_bytes(&bytes), "café");
    }

    /// Regression: UTF-16 LE BOM followed by an odd number of payload bytes
    /// must not panic or silently truncate the trailing byte.
    #[test]
    fn decode_text_bytes_handles_odd_length_utf16_le() {
        // BOM (2 bytes) + 3 payload bytes = odd-length UTF-16 payload.
        let bytes = [0xFF, 0xFE, 0x6D, 0x00, 0x79];
        let decoded = decode_text_bytes(&bytes);
        // Must return something (not panic); falls back to latin-1 of
        // the full original bytes so the caller still sees the content.
        assert!(!decoded.is_empty());
    }

    /// Regression: UTF-16 BE BOM followed by an odd number of payload bytes
    /// must not panic or silently truncate the trailing byte.
    #[test]
    fn decode_text_bytes_handles_odd_length_utf16_be() {
        let bytes = [0xFE, 0xFF, 0x00, 0x6D, 0x00];
        let decoded = decode_text_bytes(&bytes);
        assert!(!decoded.is_empty());
    }

    #[test]
    fn escape_markdown_text_escapes_asterisks() {
        let text = "This is *not* bold";
        let escaped = escape_markdown_text(text);
        assert_eq!(escaped, "This is \\*not\\* bold");
    }

    #[test]
    fn escape_markdown_text_escapes_underscores() {
        let text = "This is _not_ italic";
        let escaped = escape_markdown_text(text);
        assert_eq!(escaped, "This is \\_not\\_ italic");
    }

    #[test]
    fn escape_markdown_text_escapes_backticks() {
        let text = "This is `code` text";
        let escaped = escape_markdown_text(text);
        assert_eq!(escaped, "This is \\`code\\` text");
    }

    #[test]
    fn escape_markdown_text_escapes_brackets() {
        let text = "This is [link] text";
        let escaped = escape_markdown_text(text);
        assert_eq!(escaped, "This is \\[link\\] text");
    }

    #[test]
    fn escape_markdown_text_escapes_hash() {
        let text = "This is #heading text";
        let escaped = escape_markdown_text(text);
        assert_eq!(escaped, "This is \\#heading text");
    }

    #[test]
    fn escape_markdown_text_escapes_multiple_special_chars() {
        let text = "Variable *tracks* [documentation] with `code`";
        let escaped = escape_markdown_text(text);
        assert_eq!(escaped, "Variable \\*tracks\\* \\[documentation\\] with \\`code\\`");
    }

    #[test]
    fn escape_markdown_text_preserves_plain_text() {
        let text = "This is plain text";
        let escaped = escape_markdown_text(text);
        assert_eq!(escaped, text);
    }

    #[test]
    fn escape_markdown_text_escapes_dash() {
        // Dashes are escaped conservatively (they can start list items at line
        // start or form setext headings `---`). The output renders identically
        // in all markdown renderers — `read\-only` displays as `read-only`.
        let text = "read-only access";
        let escaped = escape_markdown_text(text);
        assert_eq!(escaped, r"read\-only access");
    }

    #[test]
    fn escape_markdown_text_escapes_backslash() {
        // Backslashes are escaped so they render as literal backslashes.
        // A comment like `C:\path\to\file` becomes `C:\\path\\to\\file`.
        let text = r"C:\path\file";
        let escaped = escape_markdown_text(text);
        assert_eq!(escaped, r"C:\\path\\file");
    }

    #[test]
    fn escape_markdown_text_handles_empty_string() {
        assert_eq!(escape_markdown_text(""), "");
    }

    #[test]
    fn escape_markdown_text_handles_unicode() {
        // Multi-byte UTF-8 should pass through unchanged.
        let text = "Résumé: *important*";
        let escaped = escape_markdown_text(text);
        assert_eq!(escaped, r"Résumé: \*important\*");
    }
}