fallow-extract 3.44.0

AST extraction engine for fallow codebase intelligence (parser, complexity, SFC / Astro / MDX / CSS)
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
//! Nesting-depth guard that runs before the Oxc parser sees a source.
//!
//! The Oxc parser and the AST visitors recurse once per nesting level and
//! have no depth limit (oxc-project/oxc#21953, oxc-project/oxc#24375). A
//! file with a few thousand nested brackets overflows the stack, and because
//! a stack overflow aborts the process, one such file kills the whole run.
//! Extraction therefore measures the bracket nesting first and does not parse
//! a file past [`MAX_NESTING_DEPTH`].
//!
//! The scan is a lexer approximation. Brackets in strings, comments and
//! template text do not count. A string or regex literal that does not end on
//! its line is not a literal, so the scan reads it again as code: a stray
//! quote in JSX text or a division read as a regex cannot hide brackets. A
//! regex body keeps its unclosed openers open, so a division that looks like
//! a regex cannot hide brackets either. It does not need to be
//! exact, because real code stays far below the cap. Nesting without brackets
//! (TypeScript generics, JSX elements, long member or call chains) is not
//! capped. [`parse_bounded`] runs such a parse on a stack that is large
//! enough for it.
//!
//! The same scan also counts the `<` tokens that the TypeScript parser can
//! try as nested type-argument lists, because each such level multiplies the
//! parse time. [`MAX_TYPE_ARGUMENT_NESTING`] caps that count.

use std::path::Path;

use fallow_types::discover::FileId;
use fallow_types::extract::ModuleInfo;

use crate::visitor::ModuleInfoExtractor;

/// Nesting depth of possible type-argument lists past which a file is not
/// parsed.
///
/// In TypeScript, the parser reads `a<` in an expression first as the start
/// of a type-argument list, and reads it again as a comparison when that
/// fails. A type can hold an expression (a computed key in `{ [key]: T }`),
/// so each `<` nested in such a list multiplies the work, and a few hundred
/// bytes such as `t<{[t<{[t<{[...` keep the parser busy for minutes. The scan
/// counts a `<` that is still open where the next one opens behind a deeper
/// `(` or `[`. One level can cost up to four times the level inside it, so
/// the cap keeps the worst case near a million steps. Real code, minified
/// bundles and generated declaration files included, stays below this cap.
const MAX_TYPE_ARGUMENT_NESTING: u32 = 10;

/// Bracket nesting depth past which a file is not parsed.
///
/// A release build on a 16 MiB worker stack overflows at about 6000 levels for
/// the most expensive shape (nested object literals), and at about half that
/// on the 8 MiB main thread that parses small projects. Real code stays far
/// below this cap.
pub const MAX_NESTING_DEPTH: u32 = 1024;

/// Nesting depth of CSS color functions past which lightningcss does not parse
/// a stylesheet.
///
/// When the content of `light-dark(`, `rgb(` or `hsl(` is not a valid color,
/// lightningcss parses it a second time as a plain function. Each level of
/// such nesting doubles the parse time. Real stylesheets nest a few color
/// functions at most, for example `color-mix(in srgb, light-dark(rgb(...)))`.
const MAX_COLOR_FUNCTION_DEPTH: usize = 8;

/// The CSS functions that lightningcss tries to parse as a color first.
const COLOR_FUNCTIONS: &[&[u8]] = &[
    b"rgb",
    b"rgba",
    b"hsl",
    b"hsla",
    b"hwb",
    b"lab",
    b"lch",
    b"oklab",
    b"oklch",
    b"color",
    b"color-mix",
    b"light-dark",
    b"alpha",
];

/// The module of a file whose bracket nesting exceeds [`MAX_NESTING_DEPTH`].
/// The module is a failed parse with no facts, so the file shows up as
/// degraded instead of aborting the run.
pub fn too_deep_module(file_id: FileId, source: &str, content_hash: u64) -> ModuleInfo {
    let mut info = ModuleInfoExtractor::new().into_module_info(
        file_id,
        content_hash,
        crate::suppress::ParsedSuppressions::default(),
    );
    info.parse_error_count = 1;
    info.parse_panicked = true;
    info.parse_nesting_too_deep = true;
    info.line_offsets = fallow_types::extract::compute_line_offsets(source);
    info
}

/// Returns `true` when the bracket nesting of `source` exceeds
/// [`MAX_NESTING_DEPTH`] or its type-argument nesting exceeds
/// [`MAX_TYPE_ARGUMENT_NESTING`].
#[cfg(test)]
#[must_use]
fn exceeds_nesting_limit(source: &str) -> bool {
    scan_nesting(source, Dialect::Script).exceeds_limits()
}

/// The lexical rules of the scanned source.
#[derive(Clone, Copy, PartialEq, Eq)]
enum Dialect {
    /// JavaScript, TypeScript and the component formats that embed them.
    Script,
    /// CSS, Sass and Less. A stylesheet has no regex or template literals, and
    /// `//` is not a comment in `url(//host/a.png)`, so only strings and
    /// `/* */` comments are skipped. A Sass `//` comment is scanned as code,
    /// which can only over-count.
    Style,
}

/// Run `parse`, which parses `source` with Oxc and walks the result, without
/// a stack overflow. Returns `None` when the bracket nesting of `source`
/// exceeds [`MAX_NESTING_DEPTH`], its type-argument nesting exceeds
/// `MAX_TYPE_ARGUMENT_NESTING` (10), or the stack it needs exceeds the cap in
/// `stack.rs`, so the caller treats the file as a failed parse.
///
/// Every parse of user source goes through this function. It sizes the stack
/// from the source length and the bracket depth, and it moves the work to a
/// thread with that stack when the current thread has too little left. A
/// parse of a fragment inside `parse` runs on the same stack and needs no
/// second call.
pub fn parse_bounded<R: Send>(source: &str, parse: impl FnOnce() -> R + Send) -> Option<R> {
    parse_bounded_as(source, Dialect::Script, parse)
}

/// [`parse_bounded`] for a lightningcss parse of stylesheet source. The
/// nesting scan uses stylesheet rules. Returns `None` also when color
/// functions nest deeper than [`MAX_COLOR_FUNCTION_DEPTH`], because the parse
/// time of lightningcss grows exponentially with that depth.
pub fn parse_style_bounded<R: Send>(source: &str, parse: impl FnOnce() -> R + Send) -> Option<R> {
    let scan = scan_depth(source, MAX_NESTING_DEPTH, Dialect::Style);
    if scan.max_colors > MAX_COLOR_FUNCTION_DEPTH {
        return None;
    }
    run_bounded(source, scan.max_depth, parse)
}

/// [`parse_bounded`] for the file at `path`. A CSS, Sass or Less file is
/// scanned with stylesheet rules.
pub fn parse_file_bounded<R: Send>(
    path: &Path,
    source: &str,
    parse: impl FnOnce() -> R + Send,
) -> Option<R> {
    let dialect = if crate::css::is_css_file(path) {
        Dialect::Style
    } else {
        Dialect::Script
    };
    parse_bounded_as(source, dialect, parse)
}

fn parse_bounded_as<R: Send>(
    source: &str,
    dialect: Dialect,
    parse: impl FnOnce() -> R + Send,
) -> Option<R> {
    let nesting = scan_nesting(source, dialect);
    if nesting.exceeds_limits() {
        return None;
    }
    run_bounded(source, nesting.brackets, parse)
}

fn run_bounded<R: Send>(source: &str, depth: u32, parse: impl FnOnce() -> R + Send) -> Option<R> {
    if depth > MAX_NESTING_DEPTH {
        return None;
    }
    let need = crate::stack::stack_need(source.len(), depth as usize)?;
    Some(crate::stack::run_with_stack(need, parse))
}

/// Parse `source` with Oxc and call `walk` with the result, through
/// [`parse_bounded`]. Returns `T::default()` when the bracket nesting exceeds
/// [`MAX_NESTING_DEPTH`].
pub fn parse_bounded_or_default<T: Send + Default>(
    source: &str,
    source_type: oxc_span::SourceType,
    walk: impl FnOnce(&oxc_parser::ParserReturn<'_>) -> T + Send,
) -> T {
    parse_bounded(source, || {
        let allocator = oxc_allocator::Allocator::default();
        let parsed = oxc_parser::Parser::new(&allocator, source, source_type).parse();
        walk(&parsed)
    })
    .unwrap_or_default()
}

/// The nesting that the parse of a source has to handle.
struct Nesting {
    /// Maximum bracket nesting depth.
    brackets: u32,
    /// Maximum nesting of `<` that can open a type-argument list.
    type_arguments: u32,
}

impl Nesting {
    const fn exceeds_limits(&self) -> bool {
        self.brackets > MAX_NESTING_DEPTH || self.type_arguments > MAX_TYPE_ARGUMENT_NESTING
    }
}

/// Measures the nesting of `source`. The scan stops as soon as a value passes
/// its limit, so each value is at most its limit + 1.
fn scan_nesting(source: &str, dialect: Dialect) -> Nesting {
    let mut scanner = Scanner::new(source, MAX_NESTING_DEPTH, dialect);
    scanner.scan();
    Nesting {
        brackets: scanner.max_depth,
        type_arguments: scanner.max_type_arguments,
    }
}

/// Maximum bracket nesting depth of `source`. The scan stops as soon as the
/// depth passes `limit`, so the result is at most `limit + 1`.
#[cfg(test)]
fn max_depth(source: &str, limit: u32, dialect: Dialect) -> u32 {
    scan_depth(source, limit, dialect).max_depth
}

fn scan_depth(source: &str, limit: u32, dialect: Dialect) -> Scanner<'_> {
    let mut scanner = Scanner::new(source, limit, dialect);
    scanner.scan();
    scanner
}

struct Scanner<'a> {
    bytes: &'a [u8],
    pos: usize,
    depth: u32,
    max_depth: u32,
    limit: u32,
    dialect: Dialect,
    /// Depth of each open `${` substitution, innermost last. The `}` that
    /// brings the depth back to this value resumes the template text.
    templates: Vec<u32>,
    /// Whether a `/` at this point starts a regex literal instead of a
    /// division, judged from the previous significant byte.
    regex_allowed: bool,
    /// Each open `<` that can start a type-argument list, outermost first.
    /// Each entry is deeper than the one before it.
    type_arguments: Vec<TypeArguments>,
    max_type_arguments: u32,
    /// Depth of each open `(` and `[`, innermost last. Only these brackets
    /// can hold an expression inside a type.
    expression_brackets: Vec<u32>,
    /// Whether this scanner reads the body of a guessed regex as code, see
    /// [`Scanner::count_regex_type_arguments`].
    regex_body: bool,
    /// Depth of each open stylesheet color function, innermost last.
    colors: Vec<u32>,
    /// Maximum number of color functions open at one time.
    max_colors: usize,
}

/// An open `<` that can start a type-argument list.
#[derive(Clone, Copy)]
struct TypeArguments {
    /// Bracket depth of the `<`.
    depth: u32,
    /// How many open lists, this one included, nest behind a `(` or `[`.
    level: u32,
}

impl<'a> Scanner<'a> {
    fn new(source: &'a str, limit: u32, dialect: Dialect) -> Self {
        Scanner {
            bytes: source.as_bytes(),
            pos: 0,
            depth: 0,
            max_depth: 0,
            limit,
            dialect,
            templates: Vec::new(),
            regex_allowed: true,
            type_arguments: Vec::new(),
            max_type_arguments: 0,
            expression_brackets: Vec::new(),
            regex_body: false,
            colors: Vec::new(),
            max_colors: 0,
        }
    }
}

impl Scanner<'_> {
    fn scan(&mut self) {
        while let Some(&byte) = self.bytes.get(self.pos) {
            if self.passed_limit() {
                return;
            }
            self.pos += 1;
            match byte {
                b'\\' | b'(' | b'/'
                    if self.dialect == Dialect::Style && self.scan_style_byte(byte) => {}
                b'(' | b'[' | b'{' => self.open_bracket(byte),
                b'}' if self.templates.last() == Some(&self.depth) => {
                    self.templates.pop();
                    self.depth -= 1;
                    self.close_type_arguments_above_depth();
                    self.skip_template_text();
                }
                b')' | b']' | b'}' => {
                    self.depth = self.depth.saturating_sub(1);
                    self.close_type_arguments_above_depth();
                    self.regex_allowed = byte == b'}';
                    self.close_color_functions();
                }
                b'<' | b'>' | b';' | b'=' | b'&' | b'|' | b'?' | b'`'
                    if self.dialect == Dialect::Script =>
                {
                    self.scan_script_byte(byte);
                }
                b'\'' | b'"' => {
                    self.skip_string(byte);
                    self.regex_allowed = false;
                }
                b'/' => self.skip_slash(),
                b' ' | b'\t' | b'\n' | b'\r' => {}
                _ => self.regex_allowed = starts_expression(byte),
            }
        }
    }

    fn open(&mut self) {
        self.depth += 1;
        self.max_depth = self.max_depth.max(self.depth);
    }

    /// Whether a nesting value passed its limit, so the scan can stop.
    const fn passed_limit(&self) -> bool {
        self.max_depth > self.limit || self.max_type_arguments > MAX_TYPE_ARGUMENT_NESTING
    }

    /// Opens a bracket. A `(` or `[` can hold an expression inside a type.
    fn open_bracket(&mut self, byte: u8) {
        self.open();
        if byte != b'{' {
            self.expression_brackets.push(self.depth);
        }
        self.regex_allowed = true;
    }

    /// Handles the script tokens that stylesheets do not have: a template
    /// literal and the tokens that open or end a type-argument list.
    fn scan_script_byte(&mut self, byte: u8) {
        match byte {
            b'`' => self.skip_template_text(),
            b'<' => {
                self.open_type_arguments();
                self.regex_allowed = true;
            }
            _ => {
                self.end_type_arguments(byte);
                self.regex_allowed = true;
            }
        }
    }

    /// Records the `<` at `pos - 1` as a possible type-argument list. A `<`
    /// at the depth of the last open one replaces it. A `<` in a deeper
    /// bracket nests one level deeper only behind a `(` or `[` opened after
    /// the enclosing `<`: a type such as `A<{ b: C<D> }>` holds no
    /// expression, so the parser does not retry it. `<=` and `<<=` cannot
    /// open a list.
    fn open_type_arguments(&mut self) {
        if self.bytes.get(self.pos) == Some(&b'<') {
            self.pos += 1;
        }
        if self.bytes.get(self.pos) == Some(&b'=') {
            return;
        }
        // A sibling `<` at the same depth keeps the level of the list that it
        // replaces. The levels match for code, and a list carried out of a
        // regex body keeps its nesting.
        let replaced = if self
            .type_arguments
            .last()
            .is_some_and(|open| open.depth == self.depth)
        {
            self.type_arguments.pop().map_or(0, |open| open.level)
        } else {
            0
        };
        let level = self
            .type_arguments
            .last()
            .map_or(1, |outer| {
                let behind_expression = self
                    .expression_brackets
                    .last()
                    .is_some_and(|&bracket| bracket > outer.depth);
                outer.level + u32::from(behind_expression)
            })
            .max(replaced);
        self.type_arguments.push(TypeArguments {
            depth: self.depth,
            level,
        });
        self.max_type_arguments = self.max_type_arguments.max(level);
    }

    /// Ends the open `<` at the current depth when the `byte` at `pos - 1`
    /// closes a type-argument list (`>`) or cannot appear in one (`;`, `=`,
    /// `&&`, `||`, `??`). The parser stops its attempt at such a token, so a
    /// later `<` is not nested in it. The arrow `=>` is valid in a type and
    /// ends nothing, and a single `&`, `|` or `?` is valid in a type too.
    fn end_type_arguments(&mut self, byte: u8) {
        let next = self.bytes.get(self.pos).copied();
        let ends = match byte {
            b'>' => self.pos < 2 || self.bytes[self.pos - 2] != b'=',
            b'=' => next != Some(b'>'),
            b'&' | b'|' | b'?' => next == Some(byte),
            _ => true,
        };
        if matches!(byte, b'&' | b'|' | b'?') && ends {
            self.pos += 1;
        }
        if ends
            && self
                .type_arguments
                .last()
                .is_some_and(|open| open.depth == self.depth)
        {
            self.type_arguments.pop();
        }
    }

    /// A closing bracket ends every `<` and every bracket opened inside it.
    fn close_type_arguments_above_depth(&mut self) {
        while self
            .type_arguments
            .last()
            .is_some_and(|open| open.depth > self.depth)
        {
            self.type_arguments.pop();
        }
        while self
            .expression_brackets
            .last()
            .is_some_and(|&bracket| bracket > self.depth)
        {
            self.expression_brackets.pop();
        }
    }

    /// Handles the stylesheet tokens that differ from script: an escape, a
    /// `/* */` comment, an unquoted `url(` body and a color function. Returns
    /// false for a `(` that opens a plain bracket.
    fn scan_style_byte(&mut self, byte: u8) -> bool {
        match byte {
            b'\\' => self.skip_escape(),
            b'/' => self.skip_block_comment(),
            _ if self.at_unquoted_url() => self.skip_unquoted_url(),
            _ if self.at_color_function() => {
                self.open();
                self.colors.push(self.depth);
                self.max_colors = self.max_colors.max(self.colors.len());
            }
            _ => return false,
        }
        true
    }

    /// Ends the color functions that a closing bracket closed.
    fn close_color_functions(&mut self) {
        while self.colors.last().is_some_and(|open| *open > self.depth) {
            self.colors.pop();
        }
    }

    /// Skips a comment, a regex literal, or a division operator.
    fn skip_slash(&mut self) {
        match self.bytes.get(self.pos) {
            Some(b'/') => {
                while self.pos < self.bytes.len() && !self.at_line_terminator() {
                    self.pos += 1;
                }
            }
            Some(b'*') => self.skip_block_comment(),
            _ if self.may_start_regex() && self.skip_regex() => {
                self.regex_allowed = false;
            }
            _ => self.regex_allowed = true,
        }
    }

    /// Whether the `(` at `pos - 1` opens an unquoted CSS `url(`, whose body is
    /// raw text: quotes, `/*` and brackets in it are not tokens.
    fn at_unquoted_url(&self) -> bool {
        let open = self.pos - 1;
        let Some(name) = open.checked_sub(3).map(|start| &self.bytes[start..open]) else {
            return false;
        };
        // A name byte or an escape before `url` makes a longer name, such as
        // `a\url(` or `\61 url(`, which is a plain function.
        let starts_word = open.checked_sub(4).is_none_or(|before| {
            let byte = self.bytes[before];
            !is_css_name_byte(byte) && byte != b'\\' && self.escape_whitespace_len(before) == 0
        });
        let body = self.bytes[self.pos..].trim_ascii_start();
        name.eq_ignore_ascii_case(b"url")
            && starts_word
            && !matches!(body.first(), Some(b'\'' | b'"'))
    }

    /// Whether the `(` at `pos - 1` opens one of the [`COLOR_FUNCTIONS`]. A
    /// name with a CSS escape such as `r\67 b(` can spell any function, so it
    /// counts as a color function.
    fn at_color_function(&self) -> bool {
        let open = self.pos - 1;
        let mut start = open;
        loop {
            while start > 0 && is_css_name_byte_or_escape(self.bytes[start - 1]) {
                start -= 1;
            }
            // The whitespace after a hex escape belongs to the name.
            match start
                .checked_sub(1)
                .map(|before| self.escape_whitespace_len(before))
            {
                Some(len) if len > 0 => start -= len,
                _ => break,
            }
        }
        let name = &self.bytes[start..open];
        name.contains(&b'\\')
            || COLOR_FUNCTIONS
                .iter()
                .any(|color| name.eq_ignore_ascii_case(color))
    }

    /// The length of the whitespace that ends at `last` when it ends a hex
    /// escape such as `\67 `, else 0. CSS reads `\r\n` as one whitespace, so
    /// it has length 2.
    fn escape_whitespace_len(&self, last: usize) -> usize {
        match self.bytes[last] {
            b'\n'
                if last > 0 && self.bytes[last - 1] == b'\r' && self.ends_hex_escape(last - 1) =>
            {
                2
            }
            b' ' | b'\t' | b'\n' | b'\r' | 0x0C if self.ends_hex_escape(last) => 1,
            _ => 0,
        }
    }

    /// Whether a hex escape such as `\67` ends right before `end`.
    fn ends_hex_escape(&self, end: usize) -> bool {
        let digits = self.bytes[..end]
            .iter()
            .rev()
            .take(MAX_HEX_ESCAPE_DIGITS + 1)
            .take_while(|byte| byte.is_ascii_hexdigit())
            .count();
        (1..=MAX_HEX_ESCAPE_DIGITS).contains(&digits)
            && end
                .checked_sub(digits + 1)
                .is_some_and(|slash| self.bytes[slash] == b'\\')
    }

    /// Skips an unquoted `url(` body up to its `)`. Quotes and `/*` in it are
    /// raw text. Its brackets still count, as in a regex body: a `(` that only
    /// looks like `url(` must not hide nesting. A CSS escape skips the next
    /// character.
    fn skip_unquoted_url(&mut self) {
        self.open();
        let mut local = 0_u32;
        let mut peak = 0_u32;
        while let Some(&byte) = self.bytes.get(self.pos) {
            self.pos += 1;
            match byte {
                b'\\' => self.skip_escape(),
                b'(' | b'[' | b'{' => {
                    local += 1;
                    peak = peak.max(local);
                }
                b')' if local == 0 => break,
                b')' | b']' | b'}' => local = local.saturating_sub(1),
                _ => {}
            }
        }
        self.max_depth = self.max_depth.max(self.depth + peak);
        self.depth = self.depth - 1 + local;
    }

    /// Skips a `/* */` comment when one starts at the `/` at `pos - 1`.
    fn skip_block_comment(&mut self) {
        if self.bytes.get(self.pos) != Some(&b'*') {
            return;
        }
        self.pos += 1;
        while self.pos < self.bytes.len() && !self.bytes[self.pos..].starts_with(b"*/") {
            self.pos += 1;
        }
        self.pos = (self.pos + 2).min(self.bytes.len());
    }

    /// Skips a string body. A quote without a closing quote on its line is
    /// not a string, so the scan goes on after the quote as code.
    fn skip_string(&mut self, quote: u8) {
        let start = self.pos;
        while let Some(&byte) = self.bytes.get(self.pos) {
            self.pos += 1;
            match byte {
                b'\\' => self.skip_escape(),
                // A string may hold U+2028 and U+2029 since ES2019. A form
                // feed is a newline in CSS.
                b'\n' | b'\r' => break,
                0x0C if self.dialect == Dialect::Style => break,
                _ if byte == quote => return,
                _ => {}
            }
        }
        self.pos = start;
    }

    /// Skips a regex body. A real regex balances its own groups, so its
    /// brackets leave the running depth as it was. A division that only looks
    /// like a regex must not hide brackets, so the body raises the peak depth
    /// and its unclosed openers stay open. A body without a closing `/` on its
    /// line is a division.
    fn skip_regex(&mut self) -> bool {
        let start = self.pos;
        // Depth before the open character class. A class closes at its first
        // `]` and its brackets are literal, so the close restores this depth.
        let mut class_base = None;
        let mut local = 0_u32;
        let mut peak = 0_u32;
        while let Some(&byte) = self.bytes.get(self.pos) {
            if self.at_line_terminator() {
                break;
            }
            self.pos += 1;
            match byte {
                // A regex cannot continue on the next line.
                b'\\' if self.at_line_terminator() => break,
                b'\\' => self.pos += 1,
                b']' if class_base.is_some() => local = class_base.take().unwrap_or(0),
                b'(' | b'[' | b'{' => {
                    if byte == b'[' && class_base.is_none() {
                        class_base = Some(local);
                    }
                    local += 1;
                    peak = peak.max(local);
                }
                b')' | b']' | b'}' => local = local.saturating_sub(1),
                b'/' if class_base.is_none() => {
                    self.max_depth = self.max_depth.max(self.depth + peak);
                    let base = self.depth;
                    self.depth += local;
                    self.count_regex_type_arguments(start, self.pos - 1, base);
                    return true;
                }
                _ => {}
            }
        }
        self.pos = start;
        false
    }

    /// Counts the `<` of the regex body `start..end` as type arguments. The
    /// parser can read the `/` as a division, so the body can be code whose
    /// type arguments nest. The body is scanned as code from bracket depth
    /// `base`, its nesting adds to the level that is open here, and the lists
    /// that stay open at its end stay open after the `/`. Inside such a scan,
    /// a further regex body counts each of its `<` as one more open level, so
    /// the work stays linear.
    fn count_regex_type_arguments(&mut self, start: usize, end: usize, base: u32) {
        let body = &self.bytes[start..end];
        if !body.contains(&b'<') {
            return;
        }
        let open = self.type_arguments.last().map_or(0, |outer| outer.level);
        if self.regex_body {
            let count = body.iter().fold(0_u32, |count, &byte| {
                count.saturating_add(u32::from(byte == b'<'))
            });
            self.carry_type_arguments(self.depth, open.saturating_add(count));
            return;
        }
        // The body starts and ends next to an ASCII `/`, so it is UTF-8.
        let Ok(text) = std::str::from_utf8(body) else {
            return;
        };
        let mut scanner = Scanner::new(text, u32::MAX, Dialect::Script);
        scanner.regex_body = true;
        scanner.scan();
        for list in &scanner.type_arguments {
            self.carry_type_arguments(base + list.depth, open.saturating_add(list.level));
        }
        for &bracket in &scanner.expression_brackets {
            let depth = (base + bracket).min(self.depth);
            if self
                .expression_brackets
                .last()
                .is_none_or(|&last| last < depth)
            {
                self.expression_brackets.push(depth);
            }
        }
        self.max_type_arguments = self
            .max_type_arguments
            .max(open.saturating_add(scanner.max_type_arguments));
    }

    /// Keeps a type-argument list of a regex body open at `depth` with
    /// `level`. The depth is at most the running depth, so a later closing
    /// bracket ends it. A list at the same depth or deeper is merged into it
    /// and keeps the higher level.
    fn carry_type_arguments(&mut self, depth: u32, level: u32) {
        let depth = depth.min(self.depth);
        let mut level = level;
        while let Some(last) = self.type_arguments.last().copied()
            && last.depth >= depth
        {
            level = level.max(last.level);
            self.type_arguments.pop();
        }
        self.type_arguments.push(TypeArguments { depth, level });
        self.max_type_arguments = self.max_type_arguments.max(level);
    }

    /// Skips template text up to the closing backtick or the next `${`,
    /// which opens one nesting level.
    fn skip_template_text(&mut self) {
        while let Some(&byte) = self.bytes.get(self.pos) {
            self.pos += 1;
            match byte {
                b'\\' => self.skip_escape(),
                b'`' => {
                    self.regex_allowed = false;
                    return;
                }
                b'$' if self.bytes.get(self.pos) == Some(&b'{') => {
                    self.pos += 1;
                    self.open();
                    self.templates.push(self.depth);
                    self.regex_allowed = true;
                    return;
                }
                _ => {}
            }
        }
    }
}

/// Whether `byte` can be part of a CSS identifier, so `myurl(` is not `url(`.
const fn is_css_name_byte(byte: u8) -> bool {
    byte.is_ascii_alphanumeric() || matches!(byte, b'-' | b'_') || byte >= 0x80
}

/// Maximum number of hex digits in a CSS escape such as `\67`.
const MAX_HEX_ESCAPE_DIGITS: usize = 6;

const fn is_css_name_byte_or_escape(byte: u8) -> bool {
    is_css_name_byte(byte) || byte == b'\\'
}

/// Keywords after which a `/` starts a regex literal.
const REGEX_KEYWORDS: &[&[u8]] = &[
    b"await",
    b"case",
    b"delete",
    b"do",
    b"else",
    b"in",
    b"instanceof",
    b"new",
    b"of",
    b"return",
    b"throw",
    b"typeof",
    b"void",
    b"yield",
];

impl Scanner<'_> {
    /// Whether the `/` at `pos - 1` can start a regex literal. In `</` and
    /// `/>` it is part of a JSX tag.
    fn may_start_regex(&self) -> bool {
        let jsx_tag = self.pos >= 2 && self.bytes[self.pos - 2] == b'<'
            || self.bytes.get(self.pos) == Some(&b'>');
        !jsx_tag && (self.regex_allowed || self.after_keyword())
    }

    /// Whether an ECMAScript line terminator starts at `pos`: LF, CR, U+2028
    /// or U+2029. Oxc ends a comment or a regex at each of them.
    fn at_line_terminator(&self) -> bool {
        self.line_terminator_len() > 0
    }

    /// Byte length of the line terminator at `pos`, or 0. CR LF is one
    /// terminator.
    fn line_terminator_len(&self) -> usize {
        match self.bytes.get(self.pos..) {
            Some([b'\r', b'\n', ..]) => 2,
            Some([b'\n' | b'\r', ..]) => 1,
            Some([0xE2, 0x80, 0xA8 | 0xA9, ..]) => 3,
            _ => 0,
        }
    }

    /// Steps over the character after a backslash at `pos - 1`. A backslash
    /// before a line terminator continues a string or template on the next
    /// line, so the whole terminator is skipped.
    fn skip_escape(&mut self) {
        self.pos += self.line_terminator_len().max(1);
    }

    /// Whether the word before the `/` at `pos - 1` is a keyword that a regex
    /// literal can follow.
    fn after_keyword(&self) -> bool {
        let before = &self.bytes[..self.pos - 1];
        let before = before.trim_ascii_end();
        let start = before
            .iter()
            .rposition(|byte| !(byte.is_ascii_alphanumeric() || matches!(byte, b'_' | b'$')))
            .map_or(0, |index| index + 1);
        REGEX_KEYWORDS.contains(&&before[start..])
    }
}

/// Whether a `/` after `byte` starts a regex literal. After an identifier,
/// a number or a closing bracket it is a division.
const fn starts_expression(byte: u8) -> bool {
    !(byte.is_ascii_alphanumeric() || matches!(byte, b'_' | b'$' | b'.' | b')' | b']'))
}

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

    fn depth_of(source: &str) -> u32 {
        max_depth(source, u32::MAX, Dialect::Script)
    }

    fn style_depth_of(source: &str) -> u32 {
        max_depth(source, u32::MAX, Dialect::Style)
    }

    #[test]
    fn style_sources_skip_strings_and_block_comments_only() {
        assert_eq!(style_depth_of(".a{content:\"(((\"}/* [[[ */"), 1);
        assert_eq!(
            style_depth_of(".b{background:url(//cdn.example.com/a.png)}.c{a:b(c(d))}"),
            3
        );
        assert_eq!(style_depth_of(".d{width:calc(100%/3)}"), 2);
        assert_eq!(
            style_depth_of(".e::before{content:'it\\'s'}.f{g:h((i))}"),
            3
        );
        // A CSS escape is not a quote, and an unquoted url() body is raw text.
        assert_eq!(style_depth_of(".g\\\"{a:b((c))}"), 3);
        assert_eq!(style_depth_of(".h{a:url(/*x.png)}.i{a:b((c))}"), 3);
        assert_eq!(style_depth_of(".j{a:url(it's.png)}.k{a:b((c))}"), 3);
        assert_eq!(style_depth_of(".l{a:URL( \"(((\" )}"), 2);
        assert_eq!(style_depth_of(".m{a:myurl(((b)))}"), 4);
        // A url() body still counts its brackets, so a misread url( hides
        // nothing.
        assert_eq!(style_depth_of("#url({{{{"), 5);
        assert_eq!(style_depth_of(".n{a:\"x\u{c}((((1"), 5);
    }

    fn color_depth_of(source: &str) -> usize {
        scan_depth(source, u32::MAX, Dialect::Style).max_colors
    }

    #[test]
    fn counts_nested_color_functions() {
        assert_eq!(color_depth_of(".a{color:red}"), 0);
        assert_eq!(
            color_depth_of(".a{color:color-mix(in srgb, LIGHT-DARK(rgb(0 0 0), red), red)}"),
            3
        );
        // Sibling functions and plain brackets do not add depth.
        assert_eq!(color_depth_of(".a{x:rgb(1 2 3) hsl(1 2% 3%) calc((1))}"), 1);
        assert_eq!(color_depth_of(".a{x:rgb(var(--a, hsl(1 2% 3%)))}"), 2);
        // A longer name, a string and a comment are not color functions.
        assert_eq!(color_depth_of(".a{x:myrgb(no-hsl(1))}"), 0);
        assert_eq!(color_depth_of(".a{content:\"rgb(rgb(\"}/* hsl(hsl( */"), 0);
        // An unclosed color function stays open.
        assert_eq!(color_depth_of(".a{x:light-dark(((light-dark(}"), 2);
    }

    #[test]
    fn an_escaped_function_name_counts_as_a_color_function() {
        assert_eq!(color_depth_of(".a{x:r\\67 b(r\\gb(\\72\tgb(1)))}"), 3);
        assert_eq!(color_depth_of(".a{x:f\\(1)}"), 0);
        // CSS reads `\r\n` after a hex escape as one whitespace.
        assert_eq!(color_depth_of(".a{x:r\\67\r\nb(r\\67\r\nb(1))}"), 2);
    }

    /// An escape before `url` makes a longer name such as `aurl`, a plain
    /// function whose body lightningcss parses. Its color functions count.
    #[test]
    fn an_escaped_name_that_ends_in_url_is_not_a_url() {
        let nested = "rgb(".repeat(3);
        for prefix in ["a\\", "\\61 ", "\\61\r\n", "\\61\t"] {
            let source = format!(".a{{x:{prefix}url({nested}");
            // The escaped name itself can also spell a color function.
            assert!(color_depth_of(&source) >= 3, "{prefix:?}");
        }
        assert_eq!(color_depth_of(".a{x:url(rgb(rgb(}"), 0);
    }

    #[test]
    fn color_function_depth_at_the_cap_is_allowed() {
        let at_limit = format!(".a{{x:{}", "rgb(".repeat(MAX_COLOR_FUNCTION_DEPTH));
        assert!(parse_style_bounded(&at_limit, || ()).is_some());
        assert!(parse_style_bounded(&format!("{at_limit}hsl("), || ()).is_none());
    }

    #[test]
    fn counts_code_brackets_only() {
        assert_eq!(depth_of("f(a[b{c}])"), 3);
        assert_eq!(
            depth_of("'((('; \"[[[\"; `{{{`; /\\(\\(/; // (((\n/* ((( */"),
            0
        );
        assert_eq!(depth_of("`a${b(`c${d}`)}`"), 3);
        assert_eq!(depth_of("a / (b) / c"), 1);
        assert_eq!(depth_of("x = /[/(]/ + (1)"), 2);
        assert_eq!(depth_of("return /[(]/.test(a)"), 2);
    }

    #[test]
    fn misread_literals_do_not_hide_brackets() {
        assert_eq!(depth_of("x = i++ / (((1"), 3);
        assert_eq!(depth_of("x = i++ / (((1 / 2)))"), 3);
        assert_eq!(depth_of("<p>it's {{{a}}}</p>"), 3);
        let lines = "x = i++ / ((1 / 2\n".repeat(500);
        assert_eq!(depth_of(&lines), 1000);
        for terminator in ["\r", "\u{2028}", "\u{2029}"] {
            assert_eq!(depth_of(&format!("// a{terminator}(((1")), 3);
            assert_eq!(depth_of(&format!("x = i++ / a{terminator}(((1")), 3);
        }
        assert_eq!(depth_of("'a\rb' + (((1"), 3);
        assert_eq!(depth_of("((('a\\\r\n)))' + (((1"), 6);
        assert_eq!(depth_of("((('a\\\u{2028})))' + (((1"), 6);
        assert_eq!(depth_of("x = i++ /a\\\n(((1 /"), 3);
    }

    #[test]
    fn regex_character_classes_do_not_accumulate() {
        let regex = format!("x = /{}/;\n", "[a-z(][^)]".repeat(2000));
        assert_eq!(depth_of(&regex), 2);
    }

    #[test]
    fn compact_jsx_closers_keep_the_depth_balanced() {
        let line = "<ul>{xs.map(i => (<li>{i}</li>))}</ul>\n{xs.map(i => <Item {...i} />)}\n";
        assert_eq!(depth_of(line), 4);
        assert_eq!(depth_of(&line.repeat(2000)), 4);
    }

    fn type_argument_nesting_of(source: &str) -> u32 {
        scan_nesting(source, Dialect::Script).type_arguments
    }

    #[test]
    fn type_argument_nesting_counts_open_lists_behind_expression_brackets() {
        assert_eq!(type_argument_nesting_of(&"t<{[".repeat(5)), 5);
        assert_eq!(type_argument_nesting_of(&"t<({[".repeat(5)), 5);
        // A `<` at the same depth replaces the open one.
        assert_eq!(type_argument_nesting_of("f(a<b, c<d, e<(g<h))"), 2);
        // `&&`, `||`, `??` and `=` cannot appear in a type, so they end the
        // open list.
        assert_eq!(
            type_argument_nesting_of("a < b && f(c < d || g(e < f ?? h(i = j < k)))"),
            1
        );
        // An object type holds no expression, so it adds no level.
        assert_eq!(
            type_argument_nesting_of(
                "useQuery<{ data: Array<{ id: string; tags: Map<string, Set<number>> }> }>()"
            ),
            1
        );
        assert_eq!(
            type_argument_nesting_of(&format!("{}x{}", "Z<{ a: ".repeat(40), " }>".repeat(40))),
            1
        );
        // `>`, `;` and closing brackets end a list. `=>`, `<=` and `<<=` do
        // not open or end one.
        assert_eq!(
            type_argument_nesting_of(
                "for (let i = 0; i < n; i++) { if (x[i] <= y) { f(() => a <<= b) } }"
            ),
            1
        );
        assert_eq!(
            type_argument_nesting_of("<ul>{xs.map(i => <li key={i}>{i < 2}</li>)}</ul>"),
            1
        );
        // Stylesheets have no type arguments.
        assert_eq!(
            scan_nesting(&"a>{[".repeat(40), Dialect::Style).type_arguments,
            0
        );
    }

    #[test]
    fn type_argument_nesting_at_the_cap_is_allowed() {
        let at_limit = "t<{[".repeat(MAX_TYPE_ARGUMENT_NESTING as usize);
        assert!(!exceeds_nesting_limit(&at_limit));
        assert!(exceeds_nesting_limit(&format!("{at_limit}t<")));
    }

    /// After `{}` the scanner reads `/` as the start of a regex, but the
    /// parser can read it as a division. The `<` in such a body must still
    /// count.
    #[test]
    fn type_arguments_in_a_guessed_regex_body_count() {
        let nested = "t<{[".repeat(MAX_TYPE_ARGUMENT_NESTING as usize + 2);
        let close = "]".repeat(MAX_TYPE_ARGUMENT_NESTING as usize + 2);
        assert!(exceeds_nesting_limit(&format!(
            "x = {{}} / {nested}{close}/ 1"
        )));
        assert!(!exceeds_nesting_limit("const re = /<a<b<c>/; f(re)"));
    }

    /// The type-argument lists that stay open at the end of a guessed regex
    /// body stay open after its `/`, as in the parse of a division.
    #[test]
    fn open_type_arguments_of_a_guessed_regex_body_stay_open() {
        let half = MAX_TYPE_ARGUMENT_NESTING as usize / 2 + 1;
        let body = format!("{}]", "t<{[".repeat(half));
        let after = "t<{[".repeat(half);
        assert!(exceeds_nesting_limit(&format!(
            "x = {{}} / {body}/ {after}"
        )));
        // A regex class can hold a further guessed regex after an escaped
        // `\]`, which ends the class bracket only in code. That regex body
        // carries its open lists too.
        let inner = format!("[\\] {{}} / {}/ ]", "t<".repeat(half));
        assert!(exceeds_nesting_limit(&format!(
            "x = {{}} / {inner}/ {after}"
        )));
    }

    #[test]
    fn depth_at_the_cap_is_allowed() {
        let at_limit = "[".repeat(MAX_NESTING_DEPTH as usize);
        assert!(!exceeds_nesting_limit(&at_limit));
        assert!(exceeds_nesting_limit(&format!("{at_limit}[")));
    }
}