tsv_ts 0.8.0

// Token types for TypeScript/JS lexer

use std::fmt;

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[repr(u8)]
pub enum KeywordKind {
    // Declaration keywords
    Const = 0,
    Let = 1,
    Var = 2,
    // Literal keywords
    True = 3,
    False = 4,
    Null = 5,
    Undefined = 6,
    // Type keywords
    Number = 7,
    String = 8,
    Boolean = 9,
    Any = 10,
    Void = 11,
    Never = 12,
    Unknown = 13,
    Object = 14,
    Symbol = 15,
    Bigint = 16,
    // Expression keywords
    New = 17,
    // Binary operator keywords
    Instanceof = 18,
    In = 19,
    // Control flow keywords
    Return = 20,
    If = 30,
    Else = 31,
    For = 32,
    While = 33,
    Do = 34,
    Switch = 35,
    Case = 36,
    Default = 37,
    Break = 38,
    Continue = 39,
    Try = 40,
    Catch = 41,
    Finally = 42,
    Throw = 43,
    // Declaration keywords (continued)
    Function = 21,
    Class = 22,
    Enum = 49,
    // Unary keyword operators
    Typeof = 23,
    Delete = 24,
    // Async/await keywords
    Async = 25,
    Await = 26,
    // Class keywords
    This = 50,
    Super = 27,
    Extends = 28,
    // Module keywords
    Export = 29,
    Import = 44,
    From = 45,
    As = 46,
    Satisfies = 47,
    // Generator keywords
    Yield = 48,
    // Debugger
    Debugger = 51,
    // Heads a statement only sloppy code admits, but is a `ReservedWord` everywhere
    // (see `KEYWORDS`)
    With = 52,
}

impl KeywordKind {
    /// Returns the string representation of the keyword
    #[inline]
    pub const fn as_str(self) -> &'static str {
        match self {
            KeywordKind::Const => "const",
            KeywordKind::Let => "let",
            KeywordKind::Var => "var",
            KeywordKind::True => "true",
            KeywordKind::False => "false",
            KeywordKind::Null => "null",
            KeywordKind::Undefined => "undefined",
            KeywordKind::Number => "number",
            KeywordKind::String => "string",
            KeywordKind::Boolean => "boolean",
            KeywordKind::Any => "any",
            KeywordKind::Void => "void",
            KeywordKind::Never => "never",
            KeywordKind::Unknown => "unknown",
            KeywordKind::Object => "object",
            KeywordKind::Symbol => "symbol",
            KeywordKind::Bigint => "bigint",
            KeywordKind::New => "new",
            KeywordKind::Instanceof => "instanceof",
            KeywordKind::In => "in",
            KeywordKind::Return => "return",
            KeywordKind::If => "if",
            KeywordKind::Else => "else",
            KeywordKind::For => "for",
            KeywordKind::While => "while",
            KeywordKind::Do => "do",
            KeywordKind::Switch => "switch",
            KeywordKind::Case => "case",
            KeywordKind::Default => "default",
            KeywordKind::Break => "break",
            KeywordKind::Continue => "continue",
            KeywordKind::Try => "try",
            KeywordKind::Catch => "catch",
            KeywordKind::Finally => "finally",
            KeywordKind::Throw => "throw",
            KeywordKind::Function => "function",
            KeywordKind::Class => "class",
            KeywordKind::Enum => "enum",
            KeywordKind::Typeof => "typeof",
            KeywordKind::Delete => "delete",
            KeywordKind::Async => "async",
            KeywordKind::Await => "await",
            KeywordKind::This => "this",
            KeywordKind::Super => "super",
            KeywordKind::Extends => "extends",
            KeywordKind::Export => "export",
            KeywordKind::Import => "import",
            KeywordKind::From => "from",
            KeywordKind::As => "as",
            KeywordKind::Satisfies => "satisfies",
            KeywordKind::Yield => "yield",
            KeywordKind::Debugger => "debugger",
            KeywordKind::With => "with",
        }
    }

    /// Returns true if this is a type keyword (number, string, boolean, etc.)
    #[inline]
    pub const fn is_type_keyword(self) -> bool {
        matches!(
            self,
            KeywordKind::Number
                | KeywordKind::String
                | KeywordKind::Boolean
                | KeywordKind::Any
                | KeywordKind::Void
                | KeywordKind::Never
                | KeywordKind::Unknown
                | KeywordKind::Object
                | KeywordKind::Symbol
                | KeywordKind::Bigint
                | KeywordKind::Null
                | KeywordKind::Undefined
        )
    }

    /// Whether this keyword can begin an expression — as a primary (`this`, `class`,
    /// `function`, a literal), a prefix operator (`typeof`, `void`, `delete`, `await`), or a
    /// contextual word that is an ordinary `IdentifierReference` (`let`, `async`, `of`, the
    /// type keywords). The words that begin none are the statement and clause keywords and
    /// the binary keyword operators — acorn's keyword tokens without `startsExpr`, where
    /// tsc's `isStartOfExpression` agrees — plus `enum`, a `ReservedWord` tsc refuses as an
    /// expression too.
    ///
    /// The one definition two readers share: the parser's token test
    /// (`Parser::is_expression_start`) and the byte lookahead that decides whether a
    /// type-argument list's `>` is a comparison (`starts_expression_after_type_args`), so a
    /// word one of them takes as an operand cannot be one the other reads as a clause.
    ///
    /// `let` begins an expression, unlike `const` / `var`: it is no `ReservedWord`, so it is
    /// an ordinary `IdentifierReference` and a perfectly good `AssignmentExpression` — which is
    /// what `YieldExpression : yield [no LT] AssignmentExpression` takes, so
    /// `function* g() { yield let; }` is `yield (let)`, as tsc and prettier read it.
    #[inline]
    pub const fn starts_expression(self) -> bool {
        !matches!(
            self,
            KeywordKind::Const
                | KeywordKind::Var
                | KeywordKind::If
                | KeywordKind::Else
                | KeywordKind::For
                | KeywordKind::While
                | KeywordKind::Do
                | KeywordKind::Switch
                | KeywordKind::Case
                | KeywordKind::Default
                | KeywordKind::Break
                | KeywordKind::Continue
                | KeywordKind::Try
                | KeywordKind::Catch
                | KeywordKind::Finally
                | KeywordKind::Throw
                | KeywordKind::Return
                | KeywordKind::Export
                | KeywordKind::Extends
                | KeywordKind::Instanceof
                | KeywordKind::In
                | KeywordKind::Enum
                | KeywordKind::Debugger
                | KeywordKind::With
        )
    }

    /// Returns true if this keyword can be used as an identifier in certain contexts.
    ///
    /// These are "contextual keywords" that only have keyword semantics in specific
    /// syntactic positions. In other positions (like variable names), they're valid identifiers.
    ///
    /// Examples:
    /// - `let async = 1;` - `async` is an identifier
    /// - `async function f() {}` - `async` is a keyword
    /// - `let from = 'x';` - `from` is an identifier
    /// - `import x from 'y';` - `from` is a keyword
    #[inline]
    pub const fn can_be_identifier(self) -> bool {
        matches!(
            self,
            // Contextual keywords that can be identifiers
            KeywordKind::Async
                | KeywordKind::Await
                | KeywordKind::From
                | KeywordKind::As
                | KeywordKind::Satisfies
                | KeywordKind::Let
                | KeywordKind::Yield
                // Type keywords are also valid identifiers in value positions
                | KeywordKind::Number
                | KeywordKind::String
                | KeywordKind::Boolean
                | KeywordKind::Any
                // ⚠️ `void` is deliberately NOT here, for the same reason
                // [`KeywordKind::can_be_binding_name`] omits it: it is a genuine
                // `ReservedWord`, so `Identifier : IdentifierName but not ReservedWord`
                // excludes it at the PRODUCTION level — not a deferrable early error.
                // tsc's parser rejects (`function void() {}` → TS1359/TS1109/TS1005) and
                // so does acorn. It sat here once, and the only position that could see
                // it was a function name, which reaches this predicate rather than the
                // binding one — so `function void() {}` parsed while `var void = 1`,
                // `class void {}` and `function f(void)` all correctly rejected.
                | KeywordKind::Never
                | KeywordKind::Unknown
                | KeywordKind::Object
                | KeywordKind::Symbol
                | KeywordKind::Bigint
                // `undefined` is a global identifier, not a ReservedWord
                | KeywordKind::Undefined
        )
    }

    /// Returns true if this keyword can be used as a binding name (variable name, parameter).
    ///
    /// Exactly [`KeywordKind::can_be_identifier`] minus `await`, and the difference
    /// is load-bearing: `await`'s bar is *goal-dependent* (reserved under
    /// `Goal::Module`, an ordinary identifier at `Goal::Script` `[~Await]`), so
    /// every caller answers it with its own `Parser::await_is_identifier` arm
    /// ordered **after** the arm that consults this predicate. Folding `await` in
    /// here would make it a binding name at Module goal.
    ///
    /// `let` and `yield` ARE binding names. Neither is excluded by a *production*:
    /// `let` is not a `ReservedWord` at all, and `BindingIdentifier[Yield, Await] :
    /// Identifier | `yield` | `await`` admits `yield` unconditionally (ecma262
    /// §sec-identifiers — the `[Yield]` bar is written as an early error, not a
    /// production guard, so that ASI can't split `let ⏎ await 0;`). Their only bar
    /// is the strict-mode Static Semantics bullet in
    /// §sec-identifiers-static-semantics-early-errors, which tsv defers to the
    /// diagnostics layer — the same bullet, and the same deferral, that already let
    /// `implements` / `interface` / `package` / `private` / `static` be binding
    /// names here (those lex as plain identifiers and never reach this predicate).
    /// Real tsc's parser accepts both in every `BindingIdentifier` position and
    /// prettier formats them.
    ///
    /// ⚠️ `void` is NOT here: it is a genuine `ReservedWord`, so `Identifier :
    /// IdentifierName but not ReservedWord` excludes it in a production.
    ///
    /// ⚠️ Two callers read this set in an *expression* context, where `yield` may be
    /// the operator instead — the single-param arrow start and object-literal
    /// shorthand both re-gate it on the parser's `in_yield`. See
    /// `Parser::parse_primary_expression`.
    ///
    /// Examples:
    /// - `const as = 1;` - valid, `as` can be a binding name
    /// - `function fn(yield: string) {}` - valid, the strict early error is deferred
    /// - `const await = 1;` - INVALID at Module goal, handled by the callers
    #[inline]
    pub const fn can_be_binding_name(self) -> bool {
        matches!(
            self,
            // Fully contextual keywords that can be binding names
            KeywordKind::Async
                | KeywordKind::From
                | KeywordKind::As
                | KeywordKind::Satisfies
                // Strict-mode-reserved by an early error only, so tsv defers
                | KeywordKind::Let
                | KeywordKind::Yield
                // Contextual type keywords are also valid binding names in value
                // positions (`let string = 1`, `class any {}`). `void` is NOT among
                // them — it is a reserved unary operator, not a contextual keyword, so
                // `let void`/`class void {}` are syntax errors (acorn/tsc reject).
                | KeywordKind::Number
                | KeywordKind::String
                | KeywordKind::Boolean
                | KeywordKind::Any
                | KeywordKind::Never
                | KeywordKind::Unknown
                | KeywordKind::Object
                | KeywordKind::Symbol
                | KeywordKind::Bigint
                // `undefined` is a global identifier, not a ReservedWord — it is
                // a valid binding name (`var undefined;`). The strict-mode
                // restriction on `undefined` is a runtime concern, not parse-time.
                | KeywordKind::Undefined
        )
        // NOTE: `await` is excluded (goal-dependent, resolved by each caller's own
        // arm) and `void` is excluded (a `ReservedWord`, barred by a production).
    }
}

impl fmt::Display for KeywordKind {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.write_str(self.as_str())
    }
}

#[derive(Debug, Clone, PartialEq, Eq)]
pub(crate) enum TokenKind {
    Number,
    String,
    Identifier,
    Keyword(KeywordKind),
    Equals,
    Colon,
    Semicolon,
    Comma,
    BraceOpen,          // {
    BraceClose,         // }
    BracketOpen,        // [
    BracketClose,       // ]
    ParenOpen,          // (
    ParenClose,         // )
    Arrow,              // =>
    Dot,                // .
    DotDotDot,          // ...
    Minus,              // -
    MinusMinus,         // --
    Plus,               // +
    PlusPlus,           // ++
    Star,               // *
    StarStar,           // **
    Slash,              // /
    Percent,            // %
    Caret,              // ^
    Tilde,              // ~
    LeftShift,          // <<
    RightShift,         // >>
    UnsignedRightShift, // >>>
    LessThan,           // <
    GreaterThan,        // >
    LessThanEquals,     // <=
    GreaterThanEquals,  // >=
    EqualsEquals,       // ==
    EqualsEqualsEquals, // ===
    BangEquals,         // !=
    BangEqualsEquals,   // !==
    Ampersand,          // &
    AmpersandAmpersand, // &&
    Pipe,               // |
    PipePipe,           // ||
    QuestionQuestion,   // ??
    QuestionDot,        // ?. (optional chaining)
    Bang,               // !
    Question,           // ?
    // Compound assignment operators
    PlusEquals,               // +=
    MinusEquals,              // -=
    StarEquals,               // *=
    SlashEquals,              // /=
    PercentEquals,            // %=
    StarStarEquals,           // **=
    LeftShiftEquals,          // <<=
    RightShiftEquals,         // >>=
    UnsignedRightShiftEquals, // >>>=
    AmpersandEquals,          // &=
    PipeEquals,               // |=
    CaretEquals,              // ^=
    AmpersandAmpersandEquals, // &&=
    PipePipeEquals,           // ||=
    QuestionQuestionEquals,   // ??=
    /// `content_start` is the byte offset where the comment's content begins
    /// (delimiters excluded): `start + 2` for `//` and `/* */`, `start` for a
    /// `#!` hashbang (whose content includes the `#!`). The end is derived by
    /// the parser (`end - 2` for block comments, `end` otherwise). Carrying the
    /// content start here keeps the lexer the single owner of delimiter widths.
    Comment {
        is_block: bool,
        content_start: u32,
    },
    // Template literal tokens
    // NoSubstitutionTemplate: `content` (no ${} interpolation)
    NoSubstitutionTemplate,
    // TemplateHead: `content${  (starts template with interpolation)
    TemplateHead,
    // TemplateMiddle: }content${  (between interpolations)
    TemplateMiddle,
    // TemplateTail: }content`  (ends template after interpolation)
    TemplateTail,
    // Regular expression literal: /pattern/flags
    // Pattern and flags are stored in token.decoded as "pattern\0flags" (null-separated)
    RegexLiteral,
    At,   // @ for decorators
    Hash, // # for private identifiers
    Eof,
}

impl TokenKind {
    /// Whether this token is a *binding-name word* — a plain identifier or a
    /// keyword-lexed word valid as a binding name (see
    /// [`KeywordKind::can_be_binding_name`]): the contextual keywords (`string`,
    /// `any`, …) **and** `let` / `yield`, whose only bar is a strict-mode early
    /// error tsv defers. Note the second group means a `ReservedWord` (`yield`)
    /// passes — this predicate is keyed on the *name* set, not on reserved-ness.
    /// Excludes `await` (a binding name only at Script `[~Await]`, handled at the
    /// sites that care) and the non-word binding starters (`[`, `{`, `...`,
    /// `this`).
    #[inline]
    pub(crate) fn is_binding_name_word(&self) -> bool {
        match self {
            TokenKind::Identifier => true,
            TokenKind::Keyword(kw) => kw.can_be_binding_name(),
            _ => false,
        }
    }
}

// TODO: Consider refining Display implementation for better error messages
// Current approach: Quoted tokens like '=', lowercase for others
// Alternative: Could match TypeScript/JS terminology more closely
// Examples:
// - "identifier token" instead of "identifier"
// - "number literal" instead of "number"
// - "string literal" instead of "string"
// Trade-off: Current is concise, alternative is more descriptive
// Usage in errors: "Expected property key, found {token_kind}"
impl fmt::Display for TokenKind {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            TokenKind::Number => write!(f, "number"),
            TokenKind::String => write!(f, "string"),
            TokenKind::Identifier => write!(f, "identifier"),
            TokenKind::Keyword(kw) => write!(f, "'{kw}'"),
            TokenKind::Equals => write!(f, "'='"),
            TokenKind::Colon => write!(f, "':'"),
            TokenKind::Semicolon => write!(f, "';'"),
            TokenKind::Comma => write!(f, "','"),
            TokenKind::BraceOpen => write!(f, "'{{'"),
            TokenKind::BraceClose => write!(f, "'}}'"),
            TokenKind::BracketOpen => write!(f, "'['"),
            TokenKind::BracketClose => write!(f, "']'"),
            TokenKind::ParenOpen => write!(f, "'('"),
            TokenKind::ParenClose => write!(f, "')'"),
            TokenKind::Arrow => write!(f, "'=>'"),
            TokenKind::Dot => write!(f, "'.'"),
            TokenKind::DotDotDot => write!(f, "'...'"),
            TokenKind::Minus => write!(f, "'-'"),
            TokenKind::MinusMinus => write!(f, "'--'"),
            TokenKind::Plus => write!(f, "'+'"),
            TokenKind::PlusPlus => write!(f, "'++'"),
            TokenKind::Star => write!(f, "'*'"),
            TokenKind::StarStar => write!(f, "'**'"),
            TokenKind::Slash => write!(f, "'/'"),
            TokenKind::Percent => write!(f, "'%'"),
            TokenKind::Caret => write!(f, "'^'"),
            TokenKind::Tilde => write!(f, "'~'"),
            TokenKind::LeftShift => write!(f, "'<<'"),
            TokenKind::RightShift => write!(f, "'>>'"),
            TokenKind::UnsignedRightShift => write!(f, "'>>>'"),
            TokenKind::LessThan => write!(f, "'<'"),
            TokenKind::GreaterThan => write!(f, "'>'"),
            TokenKind::LessThanEquals => write!(f, "'<='"),
            TokenKind::GreaterThanEquals => write!(f, "'>='"),
            TokenKind::EqualsEquals => write!(f, "'=='"),
            TokenKind::EqualsEqualsEquals => write!(f, "'==='"),
            TokenKind::BangEquals => write!(f, "'!='"),
            TokenKind::BangEqualsEquals => write!(f, "'!=='"),
            TokenKind::Ampersand => write!(f, "'&'"),
            TokenKind::AmpersandAmpersand => write!(f, "'&&'"),
            TokenKind::Pipe => write!(f, "'|'"),
            TokenKind::PipePipe => write!(f, "'||'"),
            TokenKind::QuestionQuestion => write!(f, "'??'"),
            TokenKind::QuestionDot => write!(f, "'?.'"),
            TokenKind::Bang => write!(f, "'!'"),
            TokenKind::Question => write!(f, "'?'"),
            TokenKind::PlusEquals => write!(f, "'+='"),
            TokenKind::MinusEquals => write!(f, "'-='"),
            TokenKind::StarEquals => write!(f, "'*='"),
            TokenKind::SlashEquals => write!(f, "'/='"),
            TokenKind::PercentEquals => write!(f, "'%='"),
            TokenKind::StarStarEquals => write!(f, "'**='"),
            TokenKind::LeftShiftEquals => write!(f, "'<<='"),
            TokenKind::RightShiftEquals => write!(f, "'>>='"),
            TokenKind::UnsignedRightShiftEquals => write!(f, "'>>>='"),
            TokenKind::AmpersandEquals => write!(f, "'&='"),
            TokenKind::PipeEquals => write!(f, "'|='"),
            TokenKind::CaretEquals => write!(f, "'^='"),
            TokenKind::AmpersandAmpersandEquals => write!(f, "'&&='"),
            TokenKind::PipePipeEquals => write!(f, "'||='"),
            TokenKind::QuestionQuestionEquals => write!(f, "'??='"),
            TokenKind::Comment { is_block, .. } => {
                if *is_block {
                    write!(f, "block comment")
                } else {
                    write!(f, "line comment")
                }
            }
            TokenKind::NoSubstitutionTemplate => write!(f, "template literal"),
            TokenKind::TemplateHead => write!(f, "template head"),
            TokenKind::TemplateMiddle => write!(f, "template middle"),
            TokenKind::TemplateTail => write!(f, "template tail"),
            TokenKind::RegexLiteral => write!(f, "regular expression"),
            TokenKind::At => write!(f, "'@'"),
            TokenKind::Hash => write!(f, "'#'"),
            TokenKind::Eof => write!(f, "end of input"),
        }
    }
}

// Token design: classification + span, no text
// - Raw text: extracted via source[start..end] on demand (zero duplication)
// - Decoded value (escapes only): held out-of-band on the lexer, not in the token
//   (`Lexer::decode_scratch`, borrowed via `decoded_str`), so the per-token value
//   carried on the hot pump is just classification + span
//
// This follows the "single source of truth" principle from docs/architecture.md:
// "Raw strings are NEVER duplicated in the AST" - applies to tokens too (pre-AST).
// A 16-byte POD with no heap-owning field, lexed in place on the parser's hot advance
// path (`Lexer::next_token_into`) and by value everywhere else (`Lexer::next_token`).
// Left non-`Copy` so `TokenKind` can stay non-`Copy` and avoid a
// `trivially_copy_pass_by_ref` cascade on the many `&TokenKind` params; moving an
// 8-byte `TokenKind` field is just as cheap.
#[derive(Debug, Clone)]
pub(crate) struct Token {
    pub kind: TokenKind,
    /// Byte offsets into the lexer's source. `u32` (not `usize`) keeps `Token`
    /// 16 bytes; source length is capped < 4 GiB upstream (`ErrorKind::TooLarge`).
    pub start: u32,
    pub end: u32,
}

// Guards the hot-path invariant: `Token` is a 16-byte POD with no heap-owning field,
// so the parser's in-place write of it stays one 16-byte store. Anything that re-bloats
// it — re-adding a `String`/`Box` field, widening `start`/`end` to `usize` — fails the
// test build here (an exact rustc layout, so never a consumer's build).
#[cfg(test)]
const _: () = assert!(size_of::<Token>() == 16);

/// The reserved-word set — the independent oracle the SWAR matcher is validated
/// against, **test-only**. Production recognition is the per-length compare arms
/// in [`keyword_swar`] (length ≤ 8) and [`keyword_swar_long`] (length 9/10); there
/// is no runtime keyword table. The unit tests cross-check those arms — plus
/// [`KEYWORD_MIN_LEN`]/[`KEYWORD_MAX_LEN`] and [`KEYWORD_LENGTHS_BY_FIRST_LETTER`] —
/// against this list, so adding a keyword to one without the other fails the suite.
/// The lexer's full-token identifier sweeps (`lexer::core`'s tests) grade their keyword
/// verdicts against it too.
#[cfg(test)]
pub(super) static KEYWORDS: &[(&str, KeywordKind)] = &[
    // Declaration keywords
    ("const", KeywordKind::Const),
    ("let", KeywordKind::Let),
    ("var", KeywordKind::Var),
    // Literal keywords
    ("true", KeywordKind::True),
    ("false", KeywordKind::False),
    ("null", KeywordKind::Null),
    ("undefined", KeywordKind::Undefined),
    // Type keywords
    ("number", KeywordKind::Number),
    ("string", KeywordKind::String),
    ("boolean", KeywordKind::Boolean),
    ("any", KeywordKind::Any),
    ("void", KeywordKind::Void),
    ("never", KeywordKind::Never),
    ("unknown", KeywordKind::Unknown),
    ("object", KeywordKind::Object),
    ("symbol", KeywordKind::Symbol),
    ("bigint", KeywordKind::Bigint),
    // Expression keywords
    ("new", KeywordKind::New),
    // Binary operator keywords
    ("instanceof", KeywordKind::Instanceof),
    ("in", KeywordKind::In),
    // Control flow keywords
    ("return", KeywordKind::Return),
    ("if", KeywordKind::If),
    ("else", KeywordKind::Else),
    ("for", KeywordKind::For),
    ("while", KeywordKind::While),
    ("do", KeywordKind::Do),
    ("switch", KeywordKind::Switch),
    ("case", KeywordKind::Case),
    ("default", KeywordKind::Default),
    ("break", KeywordKind::Break),
    ("continue", KeywordKind::Continue),
    ("try", KeywordKind::Try),
    ("catch", KeywordKind::Catch),
    ("finally", KeywordKind::Finally),
    ("throw", KeywordKind::Throw),
    // Declaration keywords (continued)
    ("function", KeywordKind::Function),
    ("class", KeywordKind::Class),
    ("enum", KeywordKind::Enum),
    // Unary keyword operators
    ("typeof", KeywordKind::Typeof),
    ("delete", KeywordKind::Delete),
    // Async/await keywords
    ("async", KeywordKind::Async),
    ("await", KeywordKind::Await),
    // Class keywords
    ("this", KeywordKind::This),
    ("super", KeywordKind::Super),
    ("extends", KeywordKind::Extends),
    // Module keywords
    ("export", KeywordKind::Export),
    ("import", KeywordKind::Import),
    ("from", KeywordKind::From),
    ("as", KeywordKind::As),
    ("satisfies", KeywordKind::Satisfies),
    // Generator keywords
    ("yield", KeywordKind::Yield),
    // Debugger
    ("debugger", KeywordKind::Debugger),
    // A `ReservedWord`, so it can never be a name — in either mode, even though the
    // STATEMENT it heads is admitted only by sloppy code. Left as an identifier it
    // would read `with (a);` as a call to a function named `with` and reprint it as
    // `with(a);`, silently reinterpreting a sloppy program instead of parsing it.
    ("with", KeywordKind::With),
    // Deliberately NOT listed: the contextual keywords (`interface`, `type`, `namespace`,
    // `declare`, `abstract`, `async`, …) lex as plain identifiers and the parser
    // recognizes them by value at the sites where they can begin a construct (see
    // `parser/statement`). Minting keyword tokens for them would break every
    // Identifier-expecting site (`x.type`, `const namespace = 1`).
];

/// Shortest reserved word (`as`/`in`/`if`/`do`) is 2 bytes; longest (`instanceof`) is 10.
const KEYWORD_MIN_LEN: usize = 2;
const KEYWORD_MAX_LEN: usize = 10;

/// [`KEYWORD_LENGTHS_BY_FIRST_LETTER`] is indexed by first letter and **shifted by the
/// identifier's length**, so every admitted length must be a valid `u16` shift. The
/// length gate in [`keyword_at`] is what guarantees it — this pins the two together, so
/// adding a longer reserved word fails the build here rather than silently wrapping the
/// shift in release and rejecting the new word.
const _: () = assert!(KEYWORD_MAX_LEN < u16::BITS as usize);

/// Bit `len` of entry `b - b'a'` is set when some reserved word begins with
/// lowercase-ASCII letter `b` **and** is `len` bytes long — the pre-filter's whole
/// question in one `u16`, since a keyword's length and first letter are both free
/// at the call site (the length is the identifier's span, the first byte is already
/// loaded to compute the index).
///
/// ⭐ **The length half is what earns the table.** A first-letter-only mask admits
/// every 9- or 10-byte identifier starting with one of seventeen letters into the
/// long path, and a 6-byte one starting with `f` into the length-6 compare arm — both
/// are then rejected one whole compare chain later. Keying on the pair rejects
/// **39.8%** of the identifiers that reach here on a TypeScript corpus (163,833 of
/// 411,775 per pass) and **82.6%** of the ones that would otherwise take the length-9/10
/// path, for the same four instructions the letter-only test cost: the `u16` load
/// replaces a register-materialized immediate, and a letter with no reserved words at
/// all still rejects at every length (its entry is zero).
///
/// Kept exactly in sync with `KEYWORDS` by `prefilter_admits_every_keyword`, which
/// re-derives every entry.
#[rustfmt::skip]
const KEYWORD_LENGTHS_BY_FIRST_LETTER: [u16; 26] = {
    /// The reserved-word lengths for one first letter, as a bit per length.
    const fn lens(lengths: &[usize]) -> u16 {
        let mut m = 0u16;
        let mut i = 0;
        while i < lengths.len() {
            m |= 1 << lengths[i];
            i += 1;
        }
        m
    }
    [
        lens(&[2, 3, 5]),       // a: as, any, await/async
        lens(&[5, 6, 7]),       // b: break, bigint, boolean
        lens(&[4, 5, 8]),       // c: case, const/class/catch, continue
        lens(&[2, 6, 7, 8]),    // d: do, delete, default, debugger
        lens(&[4, 6, 7]),       // e: else/enum, export, extends
        lens(&[3, 4, 5, 7, 8]), // f: for, from, false, finally, function
        0,                      // g
        0,                      // h
        lens(&[2, 6, 10]),      // i: in/if, import, instanceof
        0,                      // j
        0,                      // k
        lens(&[3]),             // l: let
        0,                      // m
        lens(&[3, 4, 5, 6]),    // n: new, null, never, number
        lens(&[6]),             // o: object
        0,                      // p
        0,                      // q
        lens(&[6]),             // r: return
        lens(&[5, 6, 9]),       // s: super, string/symbol/switch, satisfies
        lens(&[3, 4, 5, 6]),    // t: try, true/this, throw, typeof
        lens(&[7, 9]),          // u: unknown, undefined
        lens(&[3, 4]),          // v: var, void
        lens(&[4, 5]),          // w: with, while
        0,                      // x
        lens(&[5]),             // y: yield
        0,                      // z
    ]
};

/// Low-`len`-bytes mask for a `u64` SWAR key (`len` ∈ 1..=8) — `u64::MAX` at `len == 8`.
/// Applied inside each [`keyword_swar`] arm, where `len` is a compile-time constant, so
/// it lowers to one `and` with an immediate (or a narrower compare) rather than the
/// `shl`/`shr` pair a runtime `len` needs.
const fn keyword_low_mask(len: u32) -> u64 {
    u64::MAX >> ((8 - len) * 8)
}

/// Encode up to 8 ASCII bytes of `s` as a little-endian `u64` — the SWAR key for a
/// keyword of length ≤ 8. Used only inside `const { … }` so each keyword constant
/// is materialized at compile time, never re-run at the call site.
const fn keyword_encode(s: &str) -> u64 {
    let b = s.as_bytes();
    let mut w = 0u64;
    let mut i = 0;
    while i < b.len() {
        w |= (b[i] as u64) << (i * 8);
        i += 1;
    }
    w
}

/// Encode up to 16 ASCII bytes of `s` as a little-endian `u128` — the SWAR key for a
/// length-9/10 keyword. The `u64` [`keyword_encode`] can't hold 9+ bytes; this is its
/// wide sibling, used only inside `const { … }` in [`keyword_swar_long`].
const fn keyword_encode_wide(s: &str) -> u128 {
    let b = s.as_bytes();
    let mut w = 0u128;
    let mut i = 0;
    while i < b.len() {
        w |= (b[i] as u128) << (i * 8);
        i += 1;
    }
    w
}

/// SWAR keyword recognition for identifiers of length **2..=8**: the caller packs
/// the identifier's bytes into a little-endian `u64` (`word` — see
/// `read_keyword_word`) and this matches it against the keyword constants of that
/// length. Returns `None` for non-keywords and for `len` outside 2..=8 — the caller
/// routes the three length-9/10 keywords (`undefined`/`satisfies`/`instanceof`) to
/// [`long_keyword`].
///
/// ⚠️ **`word`'s lanes at or past `len` are UNSPECIFIED** — on the reader's fast path
/// they are whatever bytes follow the identifier. Each arm masks them off with
/// [`keyword_low_mask`], which is a compile-time constant *here* and would be a
/// variable `shl`/`shr` pair in the reader, in front of this dispatch.
///
/// Recognizes the same length-≤8 reserved words as the `KEYWORDS` oracle, proven in
/// `swar_matches_keyword_table`. Dispatching on `len` first keeps each per-length
/// compare set tiny, and the `const { … }` encodings are compile-time constants so
/// this is pure integer comparison.
///
/// ⚠️ **`inline(always)`, not `inline`.** The lexer's front
/// (`Lexer::next_token_into_local`) runs with no stack frame, and a call anywhere on its
/// path would bring the frame back on every token. With two callers — the front's
/// [`keyword_at_in_word`] and [`keyword_at`], reached from the cold identifier finisher —
/// the plain hint left this tree out of line and the front calling it; forced, each caller
/// carries its own copy.
// No `#[expect(clippy::inline_always)]`: the lint skips a function whose body opens with
// an item statement (the `use` below), so the expectation would go unfulfilled.
#[inline(always)]
// `allow`, not `expect`: the lint fires without it, but the expectation never registers as
// fulfilled — neither on the fn nor on the `use` item itself — so `expect` reads as dead.
#[allow(clippy::enum_glob_use)] // 50 arms — the glob keeps the per-length tables readable
fn keyword_swar(word: u64, len: usize) -> Option<KeywordKind> {
    use KeywordKind::*;
    match len {
        2 => {
            let word = word & const { keyword_low_mask(2) };
            if word == const { keyword_encode("in") } {
                Some(In)
            } else if word == const { keyword_encode("if") } {
                Some(If)
            } else if word == const { keyword_encode("do") } {
                Some(Do)
            } else if word == const { keyword_encode("as") } {
                Some(As)
            } else {
                None
            }
        }
        3 => {
            let word = word & const { keyword_low_mask(3) };
            if word == const { keyword_encode("let") } {
                Some(Let)
            } else if word == const { keyword_encode("var") } {
                Some(Var)
            } else if word == const { keyword_encode("any") } {
                Some(Any)
            } else if word == const { keyword_encode("new") } {
                Some(New)
            } else if word == const { keyword_encode("for") } {
                Some(For)
            } else if word == const { keyword_encode("try") } {
                Some(Try)
            } else {
                None
            }
        }
        4 => {
            let word = word & const { keyword_low_mask(4) };
            if word == const { keyword_encode("true") } {
                Some(True)
            } else if word == const { keyword_encode("null") } {
                Some(Null)
            } else if word == const { keyword_encode("void") } {
                Some(Void)
            } else if word == const { keyword_encode("this") } {
                Some(This)
            } else if word == const { keyword_encode("from") } {
                Some(From)
            } else if word == const { keyword_encode("enum") } {
                Some(Enum)
            } else if word == const { keyword_encode("case") } {
                Some(Case)
            } else if word == const { keyword_encode("else") } {
                Some(Else)
            } else if word == const { keyword_encode("with") } {
                Some(With)
            } else {
                None
            }
        }
        5 => {
            let word = word & const { keyword_low_mask(5) };
            if word == const { keyword_encode("const") } {
                Some(Const)
            } else if word == const { keyword_encode("false") } {
                Some(False)
            } else if word == const { keyword_encode("never") } {
                Some(Never)
            } else if word == const { keyword_encode("super") } {
                Some(Super)
            } else if word == const { keyword_encode("yield") } {
                Some(Yield)
            } else if word == const { keyword_encode("while") } {
                Some(While)
            } else if word == const { keyword_encode("break") } {
                Some(Break)
            } else if word == const { keyword_encode("throw") } {
                Some(Throw)
            } else if word == const { keyword_encode("class") } {
                Some(Class)
            } else if word == const { keyword_encode("async") } {
                Some(Async)
            } else if word == const { keyword_encode("await") } {
                Some(Await)
            } else if word == const { keyword_encode("catch") } {
                Some(Catch)
            } else {
                None
            }
        }
        6 => {
            let word = word & const { keyword_low_mask(6) };
            if word == const { keyword_encode("number") } {
                Some(Number)
            } else if word == const { keyword_encode("string") } {
                Some(String)
            } else if word == const { keyword_encode("object") } {
                Some(Object)
            } else if word == const { keyword_encode("symbol") } {
                Some(Symbol)
            } else if word == const { keyword_encode("bigint") } {
                Some(Bigint)
            } else if word == const { keyword_encode("return") } {
                Some(Return)
            } else if word == const { keyword_encode("switch") } {
                Some(Switch)
            } else if word == const { keyword_encode("typeof") } {
                Some(Typeof)
            } else if word == const { keyword_encode("delete") } {
                Some(Delete)
            } else if word == const { keyword_encode("export") } {
                Some(Export)
            } else if word == const { keyword_encode("import") } {
                Some(Import)
            } else {
                None
            }
        }
        7 => {
            let word = word & const { keyword_low_mask(7) };
            if word == const { keyword_encode("boolean") } {
                Some(Boolean)
            } else if word == const { keyword_encode("unknown") } {
                Some(Unknown)
            } else if word == const { keyword_encode("default") } {
                Some(Default)
            } else if word == const { keyword_encode("finally") } {
                Some(Finally)
            } else if word == const { keyword_encode("extends") } {
                Some(Extends)
            } else {
                None
            }
        }
        8 => {
            // No mask: at `len == 8` every lane is the identifier's own.
            if word == const { keyword_encode("continue") } {
                Some(Continue)
            } else if word == const { keyword_encode("function") } {
                Some(Function)
            } else if word == const { keyword_encode("debugger") } {
                Some(Debugger)
            } else {
                None
            }
        }
        _ => None,
    }
}

/// SWAR recognition for the three length-9/10 keywords (`undefined`/`satisfies`,
/// length 9; `instanceof`, length 10). The caller packs the identifier's `len` bytes
/// little-endian into a `u128` ([`long_keyword`]) and this matches it against
/// the keyword constants of that length. A `u128` key (vs the `u64` the `len <= 8`
/// path uses) holds the extra bytes while keeping the hot ≤8 path's compares narrow.
/// Returns `None` for non-keywords and for `len` outside 9..=10; proven against the
/// `KEYWORDS` oracle in `swar_matches_keyword_table`.
#[inline]
fn keyword_swar_long(word: u128, len: usize) -> Option<KeywordKind> {
    use KeywordKind::{Instanceof, Satisfies, Undefined};
    match len {
        9 => {
            if word == const { keyword_encode_wide("undefined") } {
                Some(Undefined)
            } else if word == const { keyword_encode_wide("satisfies") } {
                Some(Satisfies)
            } else {
                None
            }
        }
        10 => {
            if word == const { keyword_encode_wide("instanceof") } {
                Some(Instanceof)
            } else {
                None
            }
        }
        _ => None,
    }
}

/// Pack the identifier at `bytes[start..start+len]` (`len` ∈ 2..=8) into a
/// little-endian `u64` keyword key for [`keyword_swar`]. Fast path: one 8-byte load
/// when 8 bytes are in bounds — **99.99%** of the calls that reach here on a TypeScript
/// corpus, since an identifier is rarely in the file's last 8 bytes. Near EOF, assemble
/// from the `len` identifier bytes (always in bounds: the identifier occupies
/// `[start, start+len)`).
///
/// **The result is only defined in its low `len` bytes.** The lanes above are the
/// identifier's own trailing bytes on the fast path and zero near EOF, and
/// [`keyword_swar`] masks them off per arm — masking here instead costs a
/// `neg`/`shl`/`shr` dependency chain on a runtime `len`, in front of the length
/// dispatch.
///
/// ⚠️ **The `first_chunk` spelling is what earns the single `movq`, and the obvious
/// spelling does not.** An eight-element `from_le_bytes([bytes[start], …,
/// bytes[start + 7]])` behind a `start + 8 <= bytes.len()` guard reads as one load
/// and is not: because the eighth byte is consumed only on the `len == 8` arm, LLVM
/// sinks that byte's load into the arm and assembles the other seven from **six
/// `movzbl` + six `shl` + six `or`**, reusing the first byte the pre-filter already
/// held. A borrowed `&[u8; 8]` has no such per-byte structure to sink, so the load
/// stays whole and the mask is unconditional.
#[inline]
fn read_keyword_word(bytes: &[u8], start: usize, len: usize) -> u64 {
    if let Some(chunk) = bytes.get(start..).and_then(|tail| tail.first_chunk::<8>()) {
        // Eight in-bounds bytes packed little-endian. The lanes at or past `len` are
        // whatever follows the identifier; `keyword_swar`'s per-length arm masks them
        // off with a CONSTANT, which is cheaper than the variable shift pair this
        // would need here (`len` is a runtime value here and a compile-time one there).
        u64::from_le_bytes(*chunk)
    } else {
        let mut w = 0u64;
        let mut i = 0;
        while i < len {
            w |= (bytes[start + i] as u64) << (i * 8);
            i += 1;
        }
        w
    }
}

/// Reserved-word lookup for the identifier `bytes[start..start+len]`
/// (`len = end - start`). The general keyword entry point (the lexer's front takes
/// [`keyword_at_in_word`]): it applies a cheap pre-filter (length 2..=10, then
/// [`keyword_prefilter_admits`]), then recognizes the
/// keyword entirely via SWAR — the 50 keywords of length ≤ 8 through [`keyword_swar`]
/// (`u64` key) and the three length-9/10 keywords
/// (`undefined`/`satisfies`/`instanceof`) through [`long_keyword`] (`u128` key).
/// No hashing on any path.
///
/// `bytes` is the lexer source and `[start, start+len)` a validated identifier, so
/// it is in bounds (a non-ASCII identifier simply matches no ASCII keyword constant
/// and falls through to `None`).
#[inline]
pub(crate) fn keyword_at(bytes: &[u8], start: usize, len: usize) -> Option<KeywordKind> {
    if !matches!(len, KEYWORD_MIN_LEN..=KEYWORD_MAX_LEN)
        || !keyword_prefilter_admits(bytes[start], len)
    {
        return None;
    }
    if len <= 8 {
        keyword_swar(read_keyword_word(bytes, start, len), len)
    } else {
        // The 2 (len 9) + 1 (len 10) keywords: SWAR over a u128.
        long_keyword(&bytes[start..start + len])
    }
}

/// [`keyword_at_in_word`]'s answer: the lookup settled from one word, or deferred to
/// [`keyword_at`].
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub(super) enum WordLookup {
    /// The name's keyword kind, `None` for a plain identifier.
    Settled(Option<KeywordKind>),
    /// The front must hand the name to the general reader: from [`keyword_at_in_word`], a
    /// name of a keyword's length starting within 8 bytes of the end of input; the front also
    /// uses it for a run stopped at a `\` or non-ASCII byte.
    Deferred,
    /// A 9- or 10-byte name the pre-filter admits, whose answer is [`long_keyword`]'s.
    Long,
}

/// [`keyword_at`] for a caller that must make no call and build no loop — the lexer's
/// frame-free front (`Lexer::next_token_into_local`). Settles the name
/// ([`WordLookup::Settled`], the lookup's answer) when its length rules out a keyword,
/// when the pre-filter rejects it, or when it is at most 8 bytes long, reading every
/// answer off one 8-byte load at `start`. A 9- or 10-byte name the pre-filter admits is
/// [`WordLookup::Long`], which the caller settles off its own frame with [`long_keyword`]:
/// the tail read needs the source slice again, and keeping it live through the pre-filter
/// costs the front two callee-saved registers. Any name of a keyword's length with fewer
/// than 8 bytes from `start` to the end of `bytes` is [`WordLookup::Deferred`], which the
/// caller hands to [`keyword_at`] off its hot path — a file has one end.
///
/// The pre-filter's first letter is the load's low byte, not a read of `bytes[start]`:
/// the caller has that byte in a register already, and a read the optimizer can merge
/// with the caller's keeps that register live across the whole identifier run — one
/// more than the front has to spare without saving a callee-saved one.
#[inline]
pub(super) fn keyword_at_in_word(bytes: &[u8], start: usize, len: usize) -> WordLookup {
    if !matches!(len, KEYWORD_MIN_LEN..=KEYWORD_MAX_LEN) {
        return WordLookup::Settled(None);
    }
    let Some(chunk) = bytes.get(start..).and_then(|tail| tail.first_chunk::<8>()) else {
        return WordLookup::Deferred;
    };
    let word = u64::from_le_bytes(*chunk);
    if !keyword_prefilter_admits(word as u8, len) {
        return WordLookup::Settled(None);
    }
    if len > 8 {
        return WordLookup::Long;
    }
    WordLookup::Settled(keyword_swar(word, len))
}

/// The reserved word a 9- or 10-byte `name` spells, if any — [`WordLookup::Long`]'s
/// lookup, reading the name's first eight bytes as one word and the one or two after it
/// as a second key: every byte it reads is the name's own, so the name is the only bound.
/// `None` for any other length.
///
/// Every 9- or 10-byte name the pre-filter admits is keyed here, not only the three that
/// match: the lexer front's [`WordLookup::Long`] handoff, and through [`keyword_at`]'s long
/// arm the general reader's names alone — one stopped at a `\` or non-ASCII byte that does
/// not continue it.
///
/// ⭐ The general form: a "this path is cold" comment names a RATE, and the rate it
/// names is usually the success rate while the cost follows the call rate.
#[inline]
pub(super) fn long_keyword(name: &[u8]) -> Option<KeywordKind> {
    let (head, rest) = name.split_first_chunk::<8>()?;
    let tail = match *rest {
        [ninth] => u16::from(ninth),
        [ninth, tenth] => u16::from_le_bytes([ninth, tenth]),
        _ => return None,
    };
    keyword_swar_long(
        u128::from(u64::from_le_bytes(*head)) | (u128::from(tail) << 64),
        name.len(),
    )
}

/// The keyword lookups' pre-filter, past their length gate (`len` in 2..=10): whether an
/// identifier of `len` bytes whose first byte is `first` has a length some reserved word
/// of its first letter has (see [`KEYWORD_LENGTHS_BY_FIRST_LETTER`]) — rejecting
/// PascalCase / `_`/`$`-led / non-keyword-letter names *and* every name whose length no
/// keyword of that letter has, all before a single compare arm runs.
#[inline]
fn keyword_prefilter_admits(first: u8, len: usize) -> bool {
    debug_assert!(matches!(len, KEYWORD_MIN_LEN..=KEYWORD_MAX_LEN));
    let idx = first.wrapping_sub(b'a');
    idx < 26 && (KEYWORD_LENGTHS_BY_FIRST_LETTER[idx as usize] >> len) & 1 != 0
}

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

    /// `keyword_at` (pre-filter + SWAR) must recognize every reserved word — otherwise
    /// the lexer would misclassify a keyword as an identifier. Also re-derives the length
    /// bounds and the first-letter mask from `KEYWORDS`, so adding or removing a keyword
    /// that shifts either invariant fails here instead of silently corrupting tokenization.
    #[test]
    fn prefilter_admits_every_keyword() {
        let mut derived = [0u16; 26];
        for &(kw, kind) in KEYWORDS {
            assert_eq!(
                keyword_at(kw.as_bytes(), 0, kw.len()),
                Some(kind),
                "keyword_at failed to recognize reserved word `{kw}`"
            );
            let len = kw.len();
            assert!(
                (KEYWORD_MIN_LEN..=KEYWORD_MAX_LEN).contains(&len),
                "reserved word `{kw}` (len {len}) is outside the pre-filter bound \
                 {KEYWORD_MIN_LEN}..={KEYWORD_MAX_LEN}"
            );
            let first = kw.as_bytes()[0];
            assert!(
                first.is_ascii_lowercase(),
                "reserved word `{kw}` does not start lowercase-ASCII"
            );
            derived[(first - b'a') as usize] |= 1u16 << len;
        }
        assert_eq!(
            derived, KEYWORD_LENGTHS_BY_FIRST_LETTER,
            "KEYWORD_LENGTHS_BY_FIRST_LETTER is out of sync with the keyword set"
        );
    }

    /// Non-keywords the gate should reject (most without hashing): PascalCase, sigil-led
    /// and single-char names, and contextual words deliberately absent from `KEYWORDS`.
    /// The pre-filter is a **membership test that decides whether a compare chain
    /// runs at all**, so its class is a failure surface of its own: narrowing it
    /// wrongly turns a reserved word into a plain identifier, and no corpus of
    /// formatted code is obliged to contain the shape that separates the class from
    /// its complement. Grade it against the `KEYWORDS` oracle over generated
    /// near-misses rather than against a spot list — every one-byte substitution at
    /// every position of every reserved word, every proper prefix, and every
    /// one-character extension, over the ASCII identifier alphabet. Both lookups are
    /// graded: [`keyword_at`] and the lexer front's [`keyword_at_in_word`], whose own
    /// load-first spelling of the pre-filter is a second copy of the class.
    #[test]
    fn keyword_at_matches_the_oracle_on_every_near_miss() {
        fn oracle(s: &str) -> Option<KeywordKind> {
            KEYWORDS
                .iter()
                .find(|(kw, _)| *kw == s)
                .map(|&(_, kind)| kind)
        }
        let alphabet: Vec<u8> = (b'a'..=b'z')
            .chain(b'A'..=b'Z')
            .chain(b'0'..=b'9')
            .chain([b'_', b'$'])
            .collect();
        let mut cases = 0_u32;
        let check = |s: &str| {
            let expected = oracle(s);
            assert_eq!(
                keyword_at(s.as_bytes(), 0, s.len()),
                expected,
                "keyword_at disagrees with the KEYWORDS oracle on `{s}`"
            );
            // The front's form, with a whole word in bounds and at the end of the input:
            // whatever it settles — itself or through `long_keyword` — is the oracle's
            // answer, it hands `long_keyword` exactly the admitted 9- and 10-byte names, and
            // with a word in bounds it defers nothing.
            let padded = format!("{s});\n\t\t\t\t\t\t");
            for bytes in [padded.as_bytes(), s.as_bytes()] {
                match keyword_at_in_word(bytes, 0, s.len()) {
                    WordLookup::Settled(settled) => assert_eq!(
                        settled, expected,
                        "keyword_at_in_word disagrees with the KEYWORDS oracle on `{s}`"
                    ),
                    WordLookup::Long => {
                        assert!(
                            matches!(s.len(), 9 | 10),
                            "keyword_at_in_word handed on `{s}` as a long name"
                        );
                        assert_eq!(
                            long_keyword(s.as_bytes()),
                            expected,
                            "long_keyword disagrees with the KEYWORDS oracle on `{s}`"
                        );
                    }
                    WordLookup::Deferred => assert!(
                        bytes.len() < 8,
                        "keyword_at_in_word deferred `{s}` with a whole word in bounds"
                    ),
                }
            }
            // `long_keyword` itself, over every length: `None` outside 9..=10.
            if !matches!(s.len(), 9 | 10) {
                assert_eq!(long_keyword(s.as_bytes()), None, "long_keyword on `{s}`");
            }
        };
        for &(kw, _) in KEYWORDS {
            check(kw);
            for position in 0..kw.len() {
                for &byte in &alphabet {
                    let mut bytes = kw.as_bytes().to_vec();
                    bytes[position] = byte;
                    check(std::str::from_utf8(&bytes).unwrap());
                    cases += 1;
                }
            }
            for cut in 1..kw.len() {
                check(&kw[..cut]);
            }
            for &byte in &alphabet {
                let mut extended = kw.to_string();
                extended.push(byte as char);
                check(&extended);
            }
        }
        assert!(
            cases > 15_000,
            "the near-miss sweep collapsed to {cases} cases"
        );
    }

    #[test]
    fn prefilter_rejects_non_keywords() {
        for s in [
            "Foo",
            "_private",
            "$x",
            "x",
            "",
            "interface",
            "readonly",
            "namespace",
            "get",
            "kind",
            "map",
        ] {
            assert_eq!(
                keyword_at(s.as_bytes(), 0, s.len()),
                None,
                "`{s}` should not be a keyword"
            );
        }
    }

    /// The SWAR arms must agree with the `KEYWORDS` oracle for every reserved word —
    /// this proves the hand-written per-length compare sets have no typo or omission.
    /// Each word is recognized by exactly one arm: `keyword_swar` (`u64`) for length
    /// ≤ 8, `keyword_swar_long` (`u128`) for length 9/10. The other arm's `len` gate
    /// must reject it, so a keyword can never be matched by the wrong-width path.
    #[test]
    fn swar_matches_keyword_table() {
        for &(kw, kind) in KEYWORDS {
            if kw.len() <= 8 {
                assert_eq!(
                    keyword_swar(keyword_encode(kw), kw.len()),
                    Some(kind),
                    "keyword_swar misclassified reserved word `{kw}`"
                );
                // Out of the long path's 9..=10 scope: its `len` gate must reject it.
                assert_eq!(
                    keyword_swar_long(keyword_encode_wide(kw), kw.len()),
                    None,
                    "keyword_swar_long should reject length-{} word `{kw}`",
                    kw.len()
                );
            } else {
                assert_eq!(
                    keyword_swar_long(keyword_encode_wide(kw), kw.len()),
                    Some(kind),
                    "keyword_swar_long misclassified reserved word `{kw}`"
                );
                // Out of the ≤8 path's scope: `keyword_swar`'s `len` gate must reject it.
                assert_eq!(
                    keyword_swar(0, kw.len()),
                    None,
                    "keyword_swar should reject length-{} word `{kw}`",
                    kw.len()
                );
            }
        }
    }

    /// The production keyword encoders (`read_keyword_word`, one 8-byte load or a
    /// byte-assembly near EOF, for length ≤ 8; `long_keyword`'s head-and-tail key for
    /// length 9/10) must produce the same little-endian word as the compile-time
    /// `keyword_encode`/`keyword_encode_wide` the SWAR constants are built from.
    /// `swar_matches_keyword_table` feeds the compile-time encoders, so without this a
    /// divergence in the runtime readers — the byte order the lexer actually runs —
    /// would pass the unit suite and only surface in the integration gates. Covers the
    /// in-bounds fast path (padded source), the near-EOF assembly path (the keyword as
    /// the final bytes), and the length-9/10 key, graded through `long_keyword`'s answer
    /// since it builds its key inline.
    ///
    /// ⚠️ The reader's fast path leaves the lanes at or past `len` as whatever follows
    /// the identifier, so what must equal `keyword_encode` is the **composition** the
    /// production path performs — the reader under `keyword_low_mask(len)`, which is
    /// where `keyword_swar` applies it. That is asserted here for both reader paths;
    /// `keyword_swar_ignores_lanes_past_len` covers the masking itself.
    #[test]
    fn read_keyword_word_matches_keyword_encode() {
        for &(kw, kind) in KEYWORDS {
            if kw.len() > 8 {
                // Wide path: `long_keyword`'s key must meet the const `keyword_encode_wide`
                // its arms compare against.
                assert_eq!(
                    long_keyword(kw.as_bytes()),
                    Some(kind),
                    "long_keyword's key disagrees with keyword_encode_wide for `{kw}`"
                );
                continue;
            }
            let mask = keyword_low_mask(kw.len() as u32);
            // Fast path: ≥ 8 bytes in bounds (trailing pad guarantees start + 8 <= len).
            let mut padded = kw.as_bytes().to_vec();
            padded.extend_from_slice(b"________");
            assert_eq!(
                read_keyword_word(&padded, 0, kw.len()) & mask,
                keyword_encode(kw),
                "fast-path read_keyword_word disagrees with keyword_encode for `{kw}`"
            );
            // Near-EOF path: the keyword is the trailing bytes (start + 8 > len for
            // len < 8; the three len-8 keywords still exercise the fast branch here).
            assert_eq!(
                read_keyword_word(kw.as_bytes(), 0, kw.len()) & mask,
                keyword_encode(kw),
                "EOF-path read_keyword_word disagrees with keyword_encode for `{kw}`"
            );
        }
    }

    /// The reader's fast path hands `keyword_swar` eight source bytes, so for every
    /// identifier shorter than eight the lanes past `len` carry **whatever follows the
    /// identifier in the file** — and the arms' `keyword_low_mask` is the only thing
    /// that stops those bytes from reaching a compare. No corpus can grade that: a
    /// missing mask still matches wherever the trailing bytes happen to be zero, which
    /// is exactly what a keyword at EOF looks like, so the shapes that separate the two
    /// spellings must be generated. Every reserved word of length ≤ 8 is re-read with
    /// every one of 256 following bytes and a spread of wider fills, and every
    /// near-miss non-keyword with the same, through the real `keyword_at` entry point.
    #[test]
    fn keyword_swar_ignores_lanes_past_len() {
        const FILLS: [u64; 6] = [
            0,
            u64::MAX,
            0x5a5a_5a5a_5a5a_5a5a,
            0xa5a5_a5a5_a5a5_a5a5,
            0x0102_0304_0506_0708,
            0x8080_8080_8080_8080,
        ];
        for &(kw, kind) in KEYWORDS {
            if kw.len() > 8 {
                continue;
            }
            let mask = keyword_low_mask(kw.len() as u32);
            for fill in FILLS {
                assert_eq!(
                    keyword_swar(keyword_encode(kw) | (fill & !mask), kw.len()),
                    Some(kind),
                    "keyword_swar lost `{kw}` under trailing fill {fill:#x}"
                );
            }
            // Through the entry point, over every possible following byte.
            for trailing in 0u8..=255 {
                let mut bytes = kw.as_bytes().to_vec();
                bytes.extend_from_slice(&[trailing; 8]);
                assert_eq!(
                    keyword_at(&bytes, 0, kw.len()),
                    Some(kind),
                    "keyword_at lost `{kw}` followed by {trailing:#04x}"
                );
            }
        }
        // The other direction: a non-keyword must not become one because its trailing
        // bytes complete a reserved word's encoding in the lanes past `len`.
        for s in [
            "value", "index", "props", "fromm", "iff", "clas", "functio", "co",
        ] {
            for trailing in 0u8..=255 {
                let mut bytes = s.as_bytes().to_vec();
                bytes.extend_from_slice(&[trailing; 8]);
                assert_eq!(
                    keyword_at(&bytes, 0, s.len()),
                    None,
                    "keyword_at promoted `{s}` followed by {trailing:#04x}"
                );
            }
        }
    }

    /// SWAR must reject non-keywords (including ones that share a keyword's length
    /// and first letter) so it never promotes an identifier to a keyword.
    #[test]
    fn swar_rejects_non_keywords() {
        for s in [
            "value", "index", "props", "Foo", "fromm", "iff", "clas", "functio",
        ] {
            assert_eq!(
                keyword_swar(keyword_encode(s), s.len()),
                None,
                "`{s}` should not be a SWAR keyword"
            );
        }
    }
}