tsv_ts 0.8.0

// JS/TypeScript string escape decoding
//
// Implements ECMAScript string escape sequences as specified in:
// https://tc39.es/ecma262/#sec-literals-string-literals
//
// Reference implementation: acorn (node_modules/acorn/dist/acorn.mjs)
// - readString()
// - readEscapedChar()
// - readCodePoint()
// - readHexChar()
//
// Template literal escapes follow similar rules with additional:
// - \` - escaped backtick (template delimiter)
// - \$ - escaped dollar (to prevent interpolation)

use tsv_lang::Error;
use tsv_lang::swar::next_byte_of;

/// Decode JS/TypeScript string escape sequences
///
/// Converts escape sequences in a string literal to their actual character values.
/// Input should be the string content WITHOUT quotes.
///
/// # Escape types supported:
/// - Simple escapes: `\n`, `\t`, `\r`, `\b`, `\f`, `\v`, `\\`, `\'`, `\"`
/// - Hex escapes: `\xHH` (2 hex digits)
/// - Unicode escapes: `\uXXXX` (4 hex digits)
/// - Codepoint escapes: `\u{X...}` (any number of hex digits, value ≤ U+10FFFF —
///   the spec caps the VALUE, so leading zeros are unbounded)
/// - Surrogate pairs: a lead escape followed by a trail escape joins into one code
///   point, in either spelling and in any combination (`\uD83D\uDE00`,
///   `\u{D83D}\u{DE00}`, and the two mixed forms all decode to `😀`). An UNPAIRED
///   half becomes U+FFFD — a UTF-8 `String` cannot hold it
/// - Octal escapes: `\0` (null), legacy octals (`\101` → 'A'; a three-digit run only
///   for a leading `0`–`3`, so `\400` is `\40` + `0`). The decode is mode-free; the
///   legacy forms are disallowed in strict code, which the parser gates over the raw
///   slice (`find_legacy_escape`). The same decoder cooks template literals, so the
///   digit-run rule reaches a template's `cooked` value too (where the untagged form is
///   a deferred `NotEscapeSequence` early error)
/// - Line continuations: `\<newline>` → empty string
/// - Invalid escapes: `\z` → 'z' (backslash ignored per spec) — including `\8` / `\9`,
///   the `NonOctalDecimalEscapeSequence`, which stands for the digit itself
///
/// # Errors
///
/// A malformed `\x` or `\u` escape — a missing or non-hex digit, an unterminated or
/// empty `\u{…}`, a value past U+10FFFF — is an error positioned at the offset into `s`
/// of the backslash that opens it. `s` is a slice of some larger text, so the caller
/// shifts that by the slice's own position (`Error::shift_position`) before the
/// error leaves it.
///
/// # Examples:
/// ```ignore
/// let mut out = String::new();
/// decode_string_escapes_into("test\\n", &mut out)?;
/// assert_eq!(out, "test\n");
/// decode_string_escapes_into("\\u{1F4A9}", &mut out)?;
/// assert_eq!(out, "💩");
/// ```
pub(crate) fn decode_string_escapes_into(s: &str, out: &mut String) -> Result<(), Error> {
    out.clear();
    out.reserve(s.len());
    let result = out;
    let mut chars = EscapeCursor { rest: s };

    loop {
        // Everything up to the next backslash is copied as one run: only a
        // backslash can change what a character decodes to.
        let run = next_byte_of(chars.rest.as_bytes(), 0, [b'\\']);
        let (plain, rest) = chars.rest.split_at(run);
        result.push_str(plain);
        // The backslash's offset into `s`, which every error this escape raises carries.
        let backslash = s.len() - rest.len();
        let Some(escape) = rest.strip_prefix('\\') else {
            // No backslash left: the run reached the end.
            break;
        };
        chars.rest = escape;
        // Handle escape sequence
        match chars.next() {
            // Simple single-character escapes
            Some('n') => result.push('\n'),
            Some('t') => result.push('\t'),
            Some('r') => result.push('\r'),
            Some('b') => result.push('\u{0008}'), // backspace
            Some('f') => result.push('\u{000C}'), // form feed
            Some('v') => result.push('\u{000B}'), // vertical tab
            Some('\\') => result.push('\\'),
            Some('\'') => result.push('\''),
            Some('"') => result.push('"'),

            // Null character
            Some('0') if !matches!(chars.peek(), Some('0'..='9')) => {
                result.push('\0');
            }

            // Hex escape: \xHH
            Some('x') => {
                let code =
                    read_hex_value(&mut chars, 2).map_err(|e| e.shift_position(backslash))?;
                // Two hex digits are at most 0xFF: a Latin-1 code point, the one range a
                // byte converts to a `char` infallibly.
                #[expect(clippy::cast_possible_truncation, reason = "two hex digits fit a byte")]
                let byte = code as u8;
                result.push(char::from(byte));
            }

            // Unicode escape: \uXXXX or \u{XXXXXX}
            Some('u') => {
                let code = read_unicode_escape_value(&mut chars)
                    .map_err(|e| e.shift_position(backslash))?;

                // A LEAD surrogate joins a following TRAIL surrogate into one
                // code point. The pairing is a property of the code UNITS, not
                // of how they were spelled — `\uD83D` and `\u{D83D}` denote the
                // same unit — so all four lead/trail spelling combinations pair,
                // and only a genuinely unpaired half falls through below.
                if (0xD800..=0xDBFF).contains(&code)
                    && let Some(trail) = take_trail_surrogate(&mut chars)
                {
                    let paired = 0x10000 + (code - 0xD800) * 0x400 + (trail - 0xDC00);
                    // A paired value is 0x10000..=0x10FFFF by construction, so
                    // it is always a scalar value.
                    debug_assert!(char::from_u32(paired).is_some());
                    result.push(char::from_u32(paired).unwrap_or(char::REPLACEMENT_CHARACTER));
                } else {
                    // `code` is ≤ 0x10FFFF, so the only value `char::from_u32`
                    // refuses is an unpaired surrogate (U+D800..=U+DFFF) — well-formed
                    // grammar that only the well-formed-unicode proposals reject, and
                    // that a UTF-8 Rust `String` cannot represent. Substitute U+FFFD;
                    // `raw` is a source slice, so printed output is unaffected.
                    result.push(char::from_u32(code).unwrap_or(char::REPLACEMENT_CHARACTER));
                }
            }

            // Line continuation: backslash followed by a line terminator
            // (LF, CR, CRLF, U+2028, U+2029) — consumed, contributes nothing
            Some('\n' | '\u{2028}' | '\u{2029}') => {}
            Some('\r') => {
                // Line continuation - consume \r and optional \n
                if chars.peek() == Some('\n') {
                    chars.next();
                }
            }

            // `LegacyOctalEscapeSequence` — legal only in sloppy code. The decode is
            // mode-free; strict code rejects the form at the parser's string-literal
            // seam (`find_legacy_escape` below). The digit count is NOT "up to
            // three": a third digit only when the first is `0`-`3`, so `\400` is
            // `\40` followed by a literal `0`, and `\412` is `\41` followed by a
            // literal `2` (ecma262 sec-literals-string-literals: `ZeroToThree
            // OctalDigit OctalDigit` is the only three-digit production, and
            // `FourToSeven OctalDigit` admits no third).
            Some(ch @ '0'..='7') => {
                let mut code = ch as u32 - '0' as u32;
                let max_extra = if ch <= '3' { 2 } else { 1 };
                for _ in 0..max_extra {
                    match chars.peek() {
                        Some(next_ch @ '0'..='7') => {
                            chars.next();
                            code = code * 8 + (next_ch as u32 - '0' as u32);
                        }
                        _ => break,
                    }
                }
                // The productions cap the value at 0o377 (255), always a valid scalar.
                if let Some(ch) = char::from_u32(code) {
                    result.push(ch);
                }
            }

            // Invalid escape - per spec, backslash is ignored (e.g., \z → z)
            Some(ch) => {
                result.push(ch);
            }

            // End of string after backslash (shouldn't happen in valid input)
            None => {
                result.push('\\');
            }
        }
    }

    Ok(())
}

/// Decode escapes into a freshly allocated `String` — the ergonomic wrapper over
/// [`decode_string_escapes_into`] for this file's tests and the template parser's two
/// decodes off the lexer's path: the re-run that surfaces an escape error the lexer
/// swallowed, and the decode of a template's line-terminator-normalized raw text.
/// The hot lexer path calls `_into` directly against a parked scratch buffer.
pub(crate) fn decode_string_escapes(s: &str) -> Result<String, Error> {
    let mut out = String::new();
    decode_string_escapes_into(s, &mut out)?;
    Ok(out)
}

/// Which legacy string escape [`find_legacy_escape`] found — the two carry different
/// messages, so the finder names the form rather than leaving the caller to re-read the
/// digit at an offset only this function could have produced. Mirrors the numeric axis's
/// `LeadingZeroLiteral` (`parser/scan.rs`).
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub(crate) enum LegacyEscape {
    /// `LegacyOctalEscapeSequence` — `\7`, `\101`, and `\0` followed by a decimal
    /// digit, read in base 8.
    LegacyOctal,
    /// `NonOctalDecimalEscapeSequence` — `\8` / `\9`, standing for the digit itself.
    NonOctalDecimal,
}

/// The offset within `raw` — a string literal's inner source, quotes excluded — of the
/// backslash opening the first escape strict code disallows, if there is one.
///
/// The two productions, which ecma262 sec-literals-string-literals states as one early
/// error ("It is a Syntax Error if IsStrict(this production) is true"): a
/// `LegacyOctalEscapeSequence` (`\7`, `\101`, and `\0` followed by a decimal digit) and a
/// `NonOctalDecimalEscapeSequence` (`\8`, `\9`). A bare `\0` is **not** one of them — the
/// production is `\0 [lookahead ∉ DecimalDigit]`, the NUL escape, legal in every mode.
///
/// Scanning the raw slice rather than recording the fact during the decode keeps one
/// spelling of the question for the parser's two askers: the string-literal seam, which
/// asks as it turns the token into a node, and the retroactive prologue re-check, which
/// asks about literals whose tokens are long gone. The walk is byte-wise and steps over a
/// whole escape at a time, so an escaped backslash (`\\7`) opens no escape and a
/// multi-byte escaped character cannot be mistaken for one (a UTF-8 continuation byte is
/// never `\`).
pub(crate) fn find_legacy_escape(raw: &str) -> Option<(usize, LegacyEscape)> {
    let bytes = raw.as_bytes();
    let mut i = 0;
    while i < bytes.len() {
        if bytes[i] != b'\\' {
            i += 1;
            continue;
        }
        match bytes.get(i + 1) {
            Some(b'0') if bytes.get(i + 2).is_some_and(u8::is_ascii_digit) => {
                return Some((i, LegacyEscape::LegacyOctal));
            }
            Some(b'8' | b'9') => return Some((i, LegacyEscape::NonOctalDecimal)),
            Some(b'1'..=b'7') => return Some((i, LegacyEscape::LegacyOctal)),
            _ => {}
        }
        // Step over the backslash and the character it escapes; no escape body holds
        // another backslash, so the next one this finds opens a real escape.
        i += 2;
    }
    None
}

/// The undecoded remainder of the string being decoded — the character cursor
/// the escape readers share. `Copy`, so the surrogate lookahead
/// ([`take_trail_surrogate`]) can read ahead and put the cursor back.
///
/// It holds the remainder as a `str`, which is what lets the decode loop hand
/// the bytes between two backslashes to one `push_str` instead of decoding and
/// re-encoding them a character at a time.
#[derive(Clone, Copy)]
struct EscapeCursor<'a> {
    rest: &'a str,
}

impl EscapeCursor<'_> {
    /// The next character, left in place.
    #[inline]
    fn peek(&self) -> Option<char> {
        self.rest.chars().next()
    }

    /// The next character, consumed.
    #[inline]
    fn next(&mut self) -> Option<char> {
        let mut chars = self.rest.chars();
        let ch = chars.next()?;
        self.rest = chars.as_str();
        Some(ch)
    }
}

/// Read the body of a `\u` escape — the caller has consumed the `\` and the `u` —
/// in either spelling, returning the code point it denotes (always ≤ 0x10FFFF).
///
/// One reader for both spellings is what lets the surrogate-pairing step above stay
/// spelling-agnostic; splitting it was how `'\u{D83D}\u{DE00}'` came to decode as two
/// U+FFFDs where the 4-digit spelling of the same pair gave the astral character.
///
/// Its errors (and [`read_hex_value`]'s) are built at position 0, since neither reader
/// knows where its escape began; [`decode_string_escapes_into`] shifts them to the
/// escape's backslash.
fn read_unicode_escape_value(chars: &mut EscapeCursor<'_>) -> Result<u32, Error> {
    if chars.peek() != Some('{') {
        // Standard unicode escape: \uXXXX (4 digits → 0..=0xFFFF)
        return read_hex_value(chars, 4);
    }

    // Codepoint escape: \u{X...}
    chars.next(); // consume '{'

    // `CodePoint :: HexDigits but only if MV of HexDigits ≤ 0x10FFFF` caps the
    // VALUE, not the digit count — leading zeros are unbounded, so
    // `\u{0000000000000041}` is a valid `A`. Accumulate in `u64` and stop once past
    // the cap: an arbitrarily long escape then can't overflow, while the check below
    // still sees a value greater than 0x10FFFF (and reports it unchanged for the
    // ordinary `\u{110000}` spelling).
    let mut code: u64 = 0;
    let mut any_digit = false;
    loop {
        match chars.peek() {
            Some('}') => {
                chars.next(); // consume '}'
                break;
            }
            Some(ch) => match ch.to_digit(16) {
                Some(d) => {
                    chars.next();
                    if code <= 0x10FFFF {
                        code = code * 16 + u64::from(d);
                    }
                    any_digit = true;
                }
                None => {
                    return Err(Error::invalid_syntax(
                        "Invalid unicode codepoint escape".to_string(),
                        0,
                    ));
                }
            },
            // End of input before the closing `}` — a `\u{…` escape must be
            // terminated (matches acorn).
            None => {
                return Err(Error::invalid_syntax(
                    "Unterminated unicode codepoint escape".to_string(),
                    0,
                ));
            }
        }
    }

    if !any_digit {
        return Err(Error::invalid_syntax(
            "Invalid unicode codepoint escape length".to_string(),
            0,
        ));
    }

    if code > 0x10FFFF {
        return Err(Error::invalid_syntax(
            format!("Invalid unicode codepoint: U+{code:X}"),
            0,
        ));
    }

    Ok(code as u32)
}

/// Consume a following `\u` escape when — and only when — it denotes a TRAIL
/// surrogate (U+DC00..=U+DFFF), for joining onto a lead the caller just read.
///
/// Anything else leaves `chars` exactly where it was, so the main decode loop reaches
/// that `\` itself: a *malformed* escape therefore still reports its own error from
/// the ordinary path rather than being swallowed here.
fn take_trail_surrogate(chars: &mut EscapeCursor<'_>) -> Option<u32> {
    if chars.peek() != Some('\\') {
        return None;
    }
    let saved = *chars;
    chars.next(); // consume '\\'
    if chars.peek() == Some('u') {
        chars.next(); // consume 'u'
        if let Ok(trail) = read_unicode_escape_value(chars)
            && (0xDC00..=0xDFFF).contains(&trail)
        {
            return Some(trail);
        }
    }
    *chars = saved;
    None
}

/// Read exactly N hex digits from the cursor, accumulating their value directly
/// into a `u32` — no intermediate `String` + `from_str_radix` allocation. N is at
/// most 4 (the `\xHH` / `\uXXXX` escapes), so the value never overflows.
fn read_hex_value(chars: &mut EscapeCursor<'_>, count: usize) -> Result<u32, Error> {
    let mut value: u32 = 0;
    for _ in 0..count {
        match chars.next() {
            Some(ch) => match ch.to_digit(16) {
                Some(d) => value = value * 16 + d,
                None => {
                    return Err(Error::invalid_syntax(
                        format!("Expected hex digit, found '{ch}'"),
                        0,
                    ));
                }
            },
            None => {
                return Err(Error::invalid_syntax(
                    "Unexpected end of string in escape sequence".to_string(),
                    0,
                ));
            }
        }
    }
    Ok(value)
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_simple_escapes() {
        assert_eq!(decode_string_escapes("test\\n").unwrap(), "test\n");
        assert_eq!(decode_string_escapes("test\\t\\r").unwrap(), "test\t\r");
        assert_eq!(
            decode_string_escapes("test\\\\slash").unwrap(),
            "test\\slash"
        );
        assert_eq!(decode_string_escapes("test\\'quote").unwrap(), "test'quote");
        assert_eq!(
            decode_string_escapes("test\\\"quote").unwrap(),
            "test\"quote"
        );
    }

    #[test]
    fn test_null() {
        assert_eq!(decode_string_escapes("\\0").unwrap(), "\0");
        assert_eq!(decode_string_escapes("test\\0end").unwrap(), "test\0end");
    }

    #[test]
    fn test_hex_escapes() {
        assert_eq!(decode_string_escapes("\\x41\\x42").unwrap(), "AB");
        assert_eq!(
            decode_string_escapes("test\\x20space").unwrap(),
            "test space"
        );
    }

    #[test]
    fn test_unicode_4digit() {
        assert_eq!(decode_string_escapes("\\u0041").unwrap(), "A");
        assert_eq!(decode_string_escapes("\\u00A9").unwrap(), "©");
    }

    #[test]
    fn test_unicode_codepoint() {
        assert_eq!(decode_string_escapes("\\u{41}").unwrap(), "A");
        assert_eq!(decode_string_escapes("\\u{1F4A9}").unwrap(), "💩");
    }

    #[test]
    fn test_surrogate_pairs() {
        // 💩 = U+1F4A9 = surrogate pair \uD83D\uDCA9
        assert_eq!(decode_string_escapes("\\uD83D\\uDCA9").unwrap(), "💩");
    }

    #[test]
    fn test_invalid_escape() {
        // Invalid escapes: backslash is ignored
        assert_eq!(decode_string_escapes("\\z").unwrap(), "z");
        assert_eq!(decode_string_escapes("test\\qend").unwrap(), "testqend");
    }

    /// A malformed escape is reported at its own backslash — past a multibyte character, a
    /// well-formed escape, and a lead surrogate whose would-be trail is the malformed one.
    #[test]
    fn malformed_escape_errors_point_at_their_backslash() {
        for (input, backslash) in [
            ("ab\\u{zz}", 2),
            ("\u{e9}\\x4", 2),
            ("\\n\\u12", 2),
            ("x\\u{12", 1),
            ("\\u{110000}", 0),
            ("\\u{}", 0),
            ("\\uD83D\\u{zz}", 6),
        ] {
            let error = decode_string_escapes(input).expect_err("malformed");
            assert_eq!(error.position(), Some(backslash), "{input:?}");
        }
    }

    #[test]
    fn test_line_continuation() {
        assert_eq!(decode_string_escapes("test\\\nline").unwrap(), "testline");
    }

    #[test]
    fn test_legacy_octal_escapes() {
        // Legacy octal escapes decode to their code point.
        assert_eq!(decode_string_escapes("\\101").unwrap(), "A"); // 0o101 = 65
        assert_eq!(decode_string_escapes("\\141").unwrap(), "a"); // 0o141 = 97
        // `\0` followed by a digit is an octal escape, not the null shortcut.
        assert_eq!(decode_string_escapes("\\012").unwrap(), "\n"); // 0o12 = 10
        // A third digit only after a first of `0`-`3`: `\400` is `\40` then a literal `0`,
        // `\412` is `\41` then a literal `2`, `\777` is `\77` then a literal `7`.
        assert_eq!(decode_string_escapes("\\400").unwrap(), " 0");
        assert_eq!(decode_string_escapes("\\412").unwrap(), "!2");
        assert_eq!(decode_string_escapes("\\777").unwrap(), "?7");
        assert_eq!(decode_string_escapes("\\377").unwrap(), "\u{ff}");
    }

    #[test]
    fn test_find_legacy_escape() {
        // LegacyOctalEscapeSequence, at the offset of its backslash.
        let octal = |i| Some((i, LegacyEscape::LegacyOctal));
        let decimal = |i| Some((i, LegacyEscape::NonOctalDecimal));
        assert_eq!(find_legacy_escape("\\7"), octal(0));
        assert_eq!(find_legacy_escape("a\\101b"), octal(1));
        assert_eq!(find_legacy_escape("\\00"), octal(0));
        // `\0` is the NUL escape unless a DECIMAL digit follows it — `8` and `9` count.
        assert_eq!(find_legacy_escape("\\0"), None);
        assert_eq!(find_legacy_escape("\\0x"), None);
        assert_eq!(find_legacy_escape("\\08"), octal(0));
        assert_eq!(find_legacy_escape("\\09"), octal(0));
        // NonOctalDecimalEscapeSequence.
        assert_eq!(find_legacy_escape("\\8"), decimal(0));
        assert_eq!(find_legacy_escape("\\9"), decimal(0));
        // An escaped backslash opens no escape, so the digit after it is ordinary text.
        assert_eq!(find_legacy_escape("\\\\7"), None);
        assert_eq!(find_legacy_escape("\\\\\\7"), octal(2));
        // Escapes with no legacy form, including a multi-byte escaped character.
        assert_eq!(find_legacy_escape("\\n\\t\\x41\\u0041"), None);
        assert_eq!(find_legacy_escape("\\é7"), None);
        assert_eq!(find_legacy_escape("no escapes at all"), None);
    }

    #[test]
    fn test_crlf_and_unicode_line_continuations() {
        // `\` + CRLF consumes both and contributes nothing.
        assert_eq!(decode_string_escapes("a\\\r\nb").unwrap(), "ab");
        // `\` + U+2028 / U+2029 are line continuations too.
        assert_eq!(decode_string_escapes("a\\\u{2028}b").unwrap(), "ab");
        assert_eq!(decode_string_escapes("a\\\u{2029}b").unwrap(), "ab");
    }

    #[test]
    fn test_lone_high_surrogate_falls_back_to_replacement() {
        // A high surrogate with no following low surrogate becomes U+FFFD.
        assert_eq!(decode_string_escapes("\\uD83D").unwrap(), "\u{FFFD}");
        // ...followed by a plain char: replacement, then the char.
        assert_eq!(decode_string_escapes("\\uD83Dx").unwrap(), "\u{FFFD}x");
        // ...followed by a `\u` that is NOT a low surrogate: the lookahead is
        // restored and the second escape decodes on its own.
        assert_eq!(
            decode_string_escapes("\\uD83D\\u0041").unwrap(),
            "\u{FFFD}A"
        );
    }

    #[test]
    fn test_codepoint_escape_length_and_range_errors() {
        assert!(decode_string_escapes("\\u{}").is_err()); // empty
        // `\u{1234567}` is rejected on its VALUE (0x1234567 > U+10FFFF), not on its
        // digit count — `CodePoint :: HexDigits but only if MV of HexDigits ≤ 0x10FFFF`
        // caps the value alone. See `test_codepoint_escape_leading_zeros_unbounded`.
        assert!(decode_string_escapes("\\u{1234567}").is_err());
        assert!(decode_string_escapes("\\u{110000}").is_err()); // > U+10FFFF
    }

    #[test]
    fn test_codepoint_escape_leading_zeros_unbounded() {
        // Leading zeros carry no value, so an arbitrarily long escape is valid.
        assert_eq!(decode_string_escapes("\\u{0041}").unwrap(), "A");
        assert_eq!(decode_string_escapes("\\u{0000000000000041}").unwrap(), "A");
        // Padding a value that is itself in range never pushes it out of range.
        assert_eq!(
            decode_string_escapes("\\u{00000010FFFF}").unwrap(),
            "\u{10FFFF}"
        );
        // Accumulation stops once past the cap, so an absurd escape can't overflow
        // the `u64` — it still reports as out of range.
        let long = format!("\\u{{{}}}", "f".repeat(500));
        assert!(decode_string_escapes(&long).is_err());
    }

    #[test]
    fn test_surrogate_pair_joins_in_every_spelling() {
        // The pairing is per code UNIT, so the spelling of each half is irrelevant
        // and all four combinations denote the same character.
        for pair in [
            "\\uD83D\\uDE00",
            "\\u{D83D}\\u{DE00}",
            "\\uD83D\\u{DE00}",
            "\\u{D83D}\\uDE00",
        ] {
            assert_eq!(decode_string_escapes(pair).unwrap(), "\u{1F600}", "{pair}");
        }
        // Leading zeros don't disturb the halves either.
        assert_eq!(
            decode_string_escapes("\\u{0000D83D}\\u{0DE00}").unwrap(),
            "\u{1F600}"
        );
    }

    #[test]
    fn test_unpaired_surrogate_halves_do_not_join() {
        // Two leads, or a trail before a lead, are not a pair in any spelling.
        assert_eq!(
            decode_string_escapes("\\u{D83D}\\u{D83D}").unwrap(),
            "\u{FFFD}\u{FFFD}"
        );
        assert_eq!(
            decode_string_escapes("\\u{DE00}\\u{D83D}").unwrap(),
            "\u{FFFD}\u{FFFD}"
        );
        // A lead followed by an ordinary escape keeps both: the lookahead restores
        // the iterator, so the second escape decodes through the normal path.
        assert_eq!(
            decode_string_escapes("\\uD83D\\u{41}").unwrap(),
            "\u{FFFD}A"
        );
        assert_eq!(
            decode_string_escapes("\\u{D83D}\\u0041").unwrap(),
            "\u{FFFD}A"
        );
        assert_eq!(decode_string_escapes("\\u{D83D}x").unwrap(), "\u{FFFD}x");
    }

    #[test]
    fn test_lead_surrogate_followed_by_malformed_escape_still_errors() {
        // The trail lookahead must not SWALLOW a malformed escape: it restores the
        // iterator, so the main loop reaches that `\` and reports it as it always did.
        assert!(decode_string_escapes("\\u{D83D}\\u{110000}").is_err());
        assert!(decode_string_escapes("\\uD83D\\u{}").is_err());
        assert!(decode_string_escapes("\\uD83D\\uZZZZ").is_err());
    }

    #[test]
    fn test_braced_lone_surrogate_falls_back_to_replacement() {
        // The braced spelling agrees with the 4-digit one: a lone surrogate is
        // well-formed grammar that Rust's UTF-8 `char` cannot represent.
        assert_eq!(decode_string_escapes("\\u{D800}").unwrap(), "\u{FFFD}");
        assert_eq!(decode_string_escapes("\\u{DFFF}").unwrap(), "\u{FFFD}");
        assert_eq!(decode_string_escapes("\\u{0000D800}").unwrap(), "\u{FFFD}");
        // A code point just outside the surrogate range is unaffected.
        assert_eq!(decode_string_escapes("\\u{E000}").unwrap(), "\u{E000}");
    }

    // The differential oracle: the decoder as a character-at-a-time loop over
    // `chars().peekable()`, kept verbatim as the model the run-copying decoder is
    // graded against. Never called outside these tests.
    fn model_decode_into(s: &str, out: &mut String) -> Result<(), Error> {
        out.clear();
        out.reserve(s.len());
        let result = out;
        let mut chars = s.chars().peekable();

        while let Some(ch) = chars.next() {
            if ch == '\\' {
                // The backslash's offset into `s`, counted from what is left unread — the
                // model's own arithmetic, independent of the decoder's.
                let backslash = s.len() - chars.clone().map(char::len_utf8).sum::<usize>() - 1;
                // Handle escape sequence
                match chars.next() {
                    // Simple single-character escapes
                    Some('n') => result.push('\n'),
                    Some('t') => result.push('\t'),
                    Some('r') => result.push('\r'),
                    Some('b') => result.push('\u{0008}'), // backspace
                    Some('f') => result.push('\u{000C}'), // form feed
                    Some('v') => result.push('\u{000B}'), // vertical tab
                    Some('\\') => result.push('\\'),
                    Some('\'') => result.push('\''),
                    Some('"') => result.push('"'),

                    // Null character
                    Some('0') if !matches!(chars.peek(), Some('0'..='9')) => {
                        result.push('\0');
                    }

                    // Hex escape: \xHH
                    Some('x') => {
                        let code = model_read_hex_value(&mut chars, 2)
                            .map_err(|e| e.shift_position(backslash))?;
                        #[expect(
                            clippy::cast_possible_truncation,
                            reason = "two hex digits fit a byte"
                        )]
                        let byte = code as u8;
                        result.push(char::from(byte));
                    }

                    // Unicode escape: \uXXXX or \u{XXXXXX}
                    Some('u') => {
                        let code = model_read_unicode_escape_value(&mut chars)
                            .map_err(|e| e.shift_position(backslash))?;

                        // A LEAD surrogate joins a following TRAIL surrogate into one
                        // code point. The pairing is a property of the code UNITS, not
                        // of how they were spelled — `\uD83D` and `\u{D83D}` denote the
                        // same unit — so all four lead/trail spelling combinations pair,
                        // and only a genuinely unpaired half falls through below.
                        if (0xD800..=0xDBFF).contains(&code)
                            && let Some(trail) = model_take_trail_surrogate(&mut chars)
                        {
                            let paired = 0x10000 + (code - 0xD800) * 0x400 + (trail - 0xDC00);
                            // A paired value is 0x10000..=0x10FFFF by construction, so
                            // it is always a scalar value.
                            debug_assert!(char::from_u32(paired).is_some());
                            result.push(
                                char::from_u32(paired).unwrap_or(char::REPLACEMENT_CHARACTER),
                            );
                        } else {
                            // `code` is ≤ 0x10FFFF, so the only value `char::from_u32`
                            // refuses is an unpaired surrogate (U+D800..=U+DFFF) — well-formed
                            // grammar that only the well-formed-unicode proposals reject, and
                            // that a UTF-8 Rust `String` cannot represent. Substitute U+FFFD;
                            // `raw` is a source slice, so printed output is unaffected.
                            result
                                .push(char::from_u32(code).unwrap_or(char::REPLACEMENT_CHARACTER));
                        }
                    }

                    // Line continuation: backslash followed by a line terminator
                    // (LF, CR, CRLF, U+2028, U+2029) — consumed, contributes nothing
                    Some('\n' | '\u{2028}' | '\u{2029}') => {}
                    Some('\r') => {
                        // Line continuation - consume \r and optional \n
                        if chars.peek() == Some(&'\n') {
                            chars.next();
                        }
                    }

                    // `LegacyOctalEscapeSequence` — legal only in sloppy code. The decode is
                    // mode-free; strict code rejects the form at the parser's string-literal
                    // seam (`find_legacy_escape` below). The digit count is NOT "up to
                    // three": a third digit only when the first is `0`-`3`, so `\400` is
                    // `\40` followed by a literal `0`, and `\412` is `\41` followed by a
                    // literal `2` (ecma262 sec-literals-string-literals: `ZeroToThree
                    // OctalDigit OctalDigit` is the only three-digit production, and
                    // `FourToSeven OctalDigit` admits no third).
                    Some(ch @ '0'..='7') => {
                        let mut code = ch as u32 - '0' as u32;
                        let max_extra = if ch <= '3' { 2 } else { 1 };
                        for _ in 0..max_extra {
                            match chars.peek() {
                                Some(&next_ch @ '0'..='7') => {
                                    chars.next();
                                    code = code * 8 + (next_ch as u32 - '0' as u32);
                                }
                                _ => break,
                            }
                        }
                        // The productions cap the value at 0o377 (255), always a valid scalar.
                        if let Some(ch) = char::from_u32(code) {
                            result.push(ch);
                        }
                    }

                    // Invalid escape - per spec, backslash is ignored (e.g., \z → z)
                    Some(ch) => {
                        result.push(ch);
                    }

                    // End of string after backslash (shouldn't happen in valid input)
                    None => {
                        result.push('\\');
                    }
                }
            } else {
                // Regular character
                result.push(ch);
            }
        }

        Ok(())
    }

    fn model_read_unicode_escape_value<I>(chars: &mut std::iter::Peekable<I>) -> Result<u32, Error>
    where
        I: Iterator<Item = char>,
    {
        if chars.peek() != Some(&'{') {
            // Standard unicode escape: \uXXXX (4 digits → 0..=0xFFFF)
            return model_read_hex_value(chars, 4);
        }

        // Codepoint escape: \u{X...}
        chars.next(); // consume '{'

        // `CodePoint :: HexDigits but only if MV of HexDigits ≤ 0x10FFFF` caps the
        // VALUE, not the digit count — leading zeros are unbounded, so
        // `\u{0000000000000041}` is a valid `A`. Accumulate in `u64` and stop once past
        // the cap: an arbitrarily long escape then can't overflow, while the check below
        // still sees a value greater than 0x10FFFF (and reports it unchanged for the
        // ordinary `\u{110000}` spelling).
        let mut code: u64 = 0;
        let mut any_digit = false;
        loop {
            match chars.peek() {
                Some(&'}') => {
                    chars.next(); // consume '}'
                    break;
                }
                Some(&ch) => match ch.to_digit(16) {
                    Some(d) => {
                        chars.next();
                        if code <= 0x10FFFF {
                            code = code * 16 + u64::from(d);
                        }
                        any_digit = true;
                    }
                    None => {
                        return Err(Error::invalid_syntax(
                            "Invalid unicode codepoint escape".to_string(),
                            0,
                        ));
                    }
                },
                // End of input before the closing `}` — a `\u{…` escape must be
                // terminated (matches acorn).
                None => {
                    return Err(Error::invalid_syntax(
                        "Unterminated unicode codepoint escape".to_string(),
                        0,
                    ));
                }
            }
        }

        if !any_digit {
            return Err(Error::invalid_syntax(
                "Invalid unicode codepoint escape length".to_string(),
                0,
            ));
        }

        if code > 0x10FFFF {
            return Err(Error::invalid_syntax(
                format!("Invalid unicode codepoint: U+{code:X}"),
                0,
            ));
        }

        Ok(code as u32)
    }

    fn model_take_trail_surrogate<I>(chars: &mut std::iter::Peekable<I>) -> Option<u32>
    where
        I: Iterator<Item = char> + Clone,
    {
        if chars.peek() != Some(&'\\') {
            return None;
        }
        let saved = chars.clone();
        chars.next(); // consume '\\'
        if chars.peek() == Some(&'u') {
            chars.next(); // consume 'u'
            if let Ok(trail) = model_read_unicode_escape_value(chars)
                && (0xDC00..=0xDFFF).contains(&trail)
            {
                return Some(trail);
            }
        }
        *chars = saved;
        None
    }

    fn model_read_hex_value<I>(
        chars: &mut std::iter::Peekable<I>,
        count: usize,
    ) -> Result<u32, Error>
    where
        I: Iterator<Item = char>,
    {
        let mut value: u32 = 0;
        for _ in 0..count {
            match chars.next() {
                Some(ch) => match ch.to_digit(16) {
                    Some(d) => value = value * 16 + d,
                    None => {
                        return Err(Error::invalid_syntax(
                            format!("Expected hex digit, found '{ch}'"),
                            0,
                        ));
                    }
                },
                None => {
                    return Err(Error::invalid_syntax(
                        "Unexpected end of string in escape sequence".to_string(),
                        0,
                    ));
                }
            }
        }
        Ok(value)
    }

    /// Both decoders' whole observable result for one input: the verdict (an error
    /// rendered both ways, so message and position are compared) and what was left
    /// in the output buffer, which a caller reads only on `Ok` but which must not
    /// drift either.
    fn outcome(
        decode: fn(&str, &mut String) -> Result<(), Error>,
        input: &str,
    ) -> (Result<(), String>, String) {
        // A dirty buffer: the decoder owns clearing it.
        let mut out = String::from("stale");
        let verdict = decode(input, &mut out).map_err(|e| format!("{e} / {e:?}"));
        (verdict, out)
    }

    fn assert_matches_model(input: &str) {
        assert_eq!(
            outcome(decode_string_escapes_into, input),
            outcome(model_decode_into, input),
            "decoder diverged from the model on {input:?}"
        );
    }

    /// Every escape kind, well-formed and malformed, plus the plain characters an
    /// escape body can be confused with — the alphabet the differential tests
    /// combine.
    const FRAGMENTS: &[&str] = &[
        // plain text, including the characters escape bodies are made of
        "a",
        "0",
        "7",
        "8",
        "u",
        "x",
        "{",
        "}",
        "]",
        "41",
        "DE00",
        "\u{e9}",
        "\u{1F600}",
        "\n",
        "\r",
        "\u{2028}",
        // simple escapes
        "\\n",
        "\\t",
        "\\r",
        "\\b",
        "\\f",
        "\\v",
        "\\\\",
        "\\'",
        "\\\"",
        // NUL, legacy octal, non-octal decimal
        "\\0",
        "\\1",
        "\\7",
        "\\8",
        "\\9",
        "\\101",
        "\\377",
        "\\400",
        // hex
        "\\x41",
        "\\xe9",
        "\\x4",
        "\\x",
        "\\xZZ",
        "\\x\u{e9}1",
        // four-digit unicode
        "\\u0041",
        "\\u00e9",
        "\\uD83D",
        "\\uDE00",
        "\\u",
        "\\u12",
        "\\uZZZZ",
        "\\u\u{e9}",
        // braced unicode
        "\\u{41}",
        "\\u{0000041}",
        "\\u{D83D}",
        "\\u{DE00}",
        "\\u{1F600}",
        "\\u{10FFFF}",
        "\\u{110000}",
        "\\u{}",
        "\\u{41",
        "\\u{4G}",
        "\\u{\u{e9}}",
        // identity escapes, ASCII and not
        "\\z",
        "\\\u{e9}",
        "\\\u{1F600}",
        // line continuations
        "\\\n",
        "\\\r",
        "\\\r\n",
        "\\\u{2028}",
        "\\\u{2029}",
        // a lone backslash, which only the last position leaves trailing
        "\\",
    ];

    /// [`FRAGMENTS`] plus the two plain characters spelled from their code points: a
    /// NUL, and U+2029 unescaped.
    fn fragments() -> Vec<String> {
        let mut all: Vec<String> = FRAGMENTS.iter().map(|&f| f.to_owned()).collect();
        all.push(char::from(0u8).to_string());
        all.extend(char::from_u32(0x2029).map(String::from));
        all
    }

    /// Every sequence of up to three fragments: each escape kind at the start, in
    /// the middle and at the end of its string, against every neighbour — a lead
    /// surrogate before each kind of trail, a digit after each octal, a lone
    /// backslash escaping whatever follows it.
    #[test]
    fn decoder_matches_model_over_fragment_sequences() {
        assert_matches_model("");
        let fragments = fragments();
        let mut input = String::new();
        for a in &fragments {
            assert_matches_model(a);
            for b in &fragments {
                input.clear();
                input.push_str(a);
                input.push_str(b);
                assert_matches_model(&input);
                let pair = input.len();
                for c in &fragments {
                    input.truncate(pair);
                    input.push_str(c);
                    assert_matches_model(&input);
                }
            }
        }
    }

    /// Each fragment (and each pair, for the surrogate lookahead) behind and ahead
    /// of plain runs of every length across the run scan's eight-byte stride, in
    /// ASCII and in multi-byte text — where the scan stops, and what the copy takes
    /// with it, are the two things a fragment-only sweep never moves.
    #[test]
    fn decoder_matches_model_at_every_run_alignment() {
        const ASCII: &str = "abcdefghijklmnopqrstuvwxyz";
        const WIDE: &str = "a\u{e9}b\u{4e2d}c\u{1F600}d\u{2028}e\u{e9}\u{e9}f";
        let fragments = fragments();
        let mut input = String::new();
        for filler in [ASCII, WIDE] {
            let cuts: Vec<usize> = (0..=filler.len())
                .filter(|&at| filler.is_char_boundary(at))
                .collect();
            for &lead in &cuts {
                for &tail in &[0, 1, 7, 8, 9, cuts[cuts.len() / 2], filler.len()] {
                    if !filler.is_char_boundary(tail) {
                        continue;
                    }
                    for a in &fragments {
                        for b in ["", "\\uDE00", "\\u{DE00}", "\\n", "7"] {
                            input.clear();
                            input.push_str(&filler[..lead]);
                            input.push_str(a);
                            input.push_str(b);
                            input.push_str(&filler[..tail]);
                            assert_matches_model(&input);
                        }
                    }
                }
            }
        }
    }
}