feat(ast, parser, codegen): add CommentKind::MultilineBlock (#16479)

Add `CommentKind::MultilineBlock` to indicate a block comment that has at least one linebreak, which would be useful in the Codegen and Formatter

Examples:

CommentKind::Block:
```js
/* single line block comment */
```

CommentKind::MultilineBlock

```js
/* multiline
block
 comment */
```

Maybe it would be better to rename `CommentKind::Block` to `CommentKind::SinglelineBlock.` as well

Author: Dunqing

apps/oxlint/src-js/generated/deserialize.js

@@ -5651,6 +5651,8 @@ function deserializeCommentKind(pos) {
       return "Line";
     case 1:
       return "Block";
+    case 2:
+      return "Block";
     default:
       throw Error(`Unexpected discriminant ${uint8[pos]} for CommentKind`);
   }

crates/oxc_ast/src/ast/comment.rs

@@ -17,6 +17,9 @@ pub enum CommentKind {
     Line = 0,
     /// Block comment
     Block = 1,
+    /// Multiline block comment (contains line breaks)
+    #[estree(rename = "Block")]
+    MultilineBlock = 2,
 }
 
 /// Information about a comment's position relative to a token.
@@ -172,7 +175,9 @@ impl Comment {
     pub fn content_span(&self) -> Span {
         match self.kind {
             CommentKind::Line => Span::new(self.span.start + 2, self.span.end),
-            CommentKind::Block => Span::new(self.span.start + 2, self.span.end - 2),
+            CommentKind::Block | CommentKind::MultilineBlock => {
+                Span::new(self.span.start + 2, self.span.end - 2)
+            }
         }
     }
 
@@ -185,7 +190,13 @@ impl Comment {
     /// Returns `true` if this is a block comment.
     #[inline]
     pub fn is_block(self) -> bool {
-        self.kind == CommentKind::Block
+        matches!(self.kind, CommentKind::Block | CommentKind::MultilineBlock)
+    }
+
+    /// Returns `true` if this is a multi-line block comment.
+    #[inline]
+    pub fn is_multiline_block(self) -> bool {
+        self.kind == CommentKind::MultilineBlock
     }
 
     /// Returns `true` if this comment is before a token.

crates/oxc_ast/src/generated/derive_estree.rs

@@ -3234,6 +3234,7 @@ impl ESTree for CommentKind {
         match self {
             Self::Line => JsonSafeString("Line").serialize(serializer),
             Self::Block => JsonSafeString("Block").serialize(serializer),
+            Self::MultilineBlock => JsonSafeString("Block").serialize(serializer),
         }
     }
 }

crates/oxc_codegen/src/comment.rs

@@ -3,7 +3,7 @@ use std::borrow::Cow;
 use rustc_hash::{FxHashMap, FxHashSet};
 
 use oxc_ast::{Comment, CommentKind, ast::Program};
-use oxc_syntax::line_terminator::{LineTerminatorSplitter, is_line_terminator};
+use oxc_syntax::line_terminator::LineTerminatorSplitter;
 
 use crate::{Codegen, LegalComment, options::CommentOptions};
 
@@ -128,10 +128,10 @@ impl Codegen<'_> {
         };
         let comment_source = comment.span.source_text(source_text);
         match comment.kind {
-            CommentKind::Line => {
+            CommentKind::Line | CommentKind::Block => {
                 self.print_str_escaping_script_close_tag(comment_source);
             }
-            CommentKind::Block => {
+            CommentKind::MultilineBlock => {
                 for line in LineTerminatorSplitter::new(comment_source) {
                     if !line.starts_with("/*") {
                         self.print_indent();
@@ -163,7 +163,7 @@ impl Codegen<'_> {
         let source_text = program.source_text;
         for comment in program.comments.iter().filter(|c| c.is_legal()) {
             let mut text = Cow::Borrowed(comment.span.source_text(source_text));
-            if comment.is_block() && text.contains(is_line_terminator) {
+            if comment.is_multiline_block() {
                 let mut buffer = String::with_capacity(text.len());
                 // Print block comments with our own indentation.
                 for line in LineTerminatorSplitter::new(&text) {

crates/oxc_formatter/src/formatter/trivia.rs

@@ -117,28 +117,31 @@ impl<'a> Format<'a> for FormatLeadingComments<'a> {
                 write!(f, comment);
 
                 match comment.kind {
-                    CommentKind::Block => match f.source_text().lines_after(comment.span.end) {
-                        0 => {
-                            let should_nestle =
-                                leading_comments_iter.peek().is_some_and(|next_comment| {
-                                    should_nestle_adjacent_doc_comments(
-                                        comment,
-                                        next_comment,
-                                        f.source_text(),
-                                    )
-                                });
-
-                            write!(f, [maybe_space(!should_nestle)]);
-                        }
-                        1 => {
-                            if f.source_text().get_lines_before(comment.span, f.comments()) == 0 {
-                                write!(f, [soft_line_break_or_space()]);
-                            } else {
-                                write!(f, [hard_line_break()]);
+                    CommentKind::Block | CommentKind::MultilineBlock => {
+                        match f.source_text().lines_after(comment.span.end) {
+                            0 => {
+                                let should_nestle =
+                                    leading_comments_iter.peek().is_some_and(|next_comment| {
+                                        should_nestle_adjacent_doc_comments(
+                                            comment,
+                                            next_comment,
+                                            f.source_text(),
+                                        )
+                                    });
+
+                                write!(f, [maybe_space(!should_nestle)]);
+                            }
+                            1 => {
+                                if f.source_text().get_lines_before(comment.span, f.comments()) == 0
+                                {
+                                    write!(f, [soft_line_break_or_space()]);
+                                } else {
+                                    write!(f, [hard_line_break()]);
+                                }
                             }
+                            _ => write!(f, [empty_line()]),
                         }
-                        _ => write!(f, [empty_line()]),
-                    },
+                    }
                     CommentKind::Line => match f.source_text().lines_after(comment.span.end) {
                         0 | 1 => write!(f, [hard_line_break()]),
                         _ => write!(f, [empty_line()]),

crates/oxc_linter/src/rules/typescript/ban_ts_comment.rs

@@ -1,6 +1,5 @@
 use cow_utils::CowUtils;
 use lazy_regex::Regex;
-use oxc_ast::CommentKind;
 use oxc_diagnostics::OxcDiagnostic;
 use oxc_macros::declare_oxc_lint;
 use oxc_span::Span;
@@ -193,9 +192,7 @@ impl Rule for BanTsComment {
             if let Some(captures) = find_ts_comment_directive(raw, comm.is_line()) {
                 // safe to unwrap, if capture success, it can always capture one of the four directives
                 let (directive, description) = (captures.0, captures.1);
-                if CommentKind::Block == comm.kind
-                    && (directive == "check" || directive == "nocheck")
-                {
+                if comm.is_block() && (directive == "check" || directive == "nocheck") {
                     continue;
                 }
 

crates/oxc_linter/src/rules/typescript/prefer_function_type.rs

@@ -174,7 +174,7 @@ fn check_member(member: &TSSignature, node: &AstNode<'_>, ctx: &LintContext<'_>)
                                         let single_line_comment: String = format!("//{comment}\n");
                                         comments_vec.push(single_line_comment);
                                     }
-                                    CommentKind::Block => {
+                                    CommentKind::Block | CommentKind::MultilineBlock => {
                                         let multi_line_comment: String = format!("/*{comment}*/\n");
                                         comments_vec.push(multi_line_comment);
                                     }

crates/oxc_napi/src/lib.rs

@@ -33,7 +33,7 @@ pub fn convert_utf8_to_utf16(
             Comment {
                 r#type: match comment.kind {
                     CommentKind::Line => String::from("Line"),
-                    CommentKind::Block => String::from("Block"),
+                    CommentKind::Block | CommentKind::MultilineBlock => String::from("Block"),
                 },
                 value,
                 start: span.start,

crates/oxc_parser/src/lexer/comment.rs

@@ -1,5 +1,6 @@
 use memchr::memmem::Finder;
 
+use oxc_ast::CommentKind;
 use oxc_syntax::line_terminator::is_line_terminator;
 
 use crate::diagnostics;
@@ -82,9 +83,13 @@ impl<'a> Lexer<'a> {
     /// Section 12.4 Multi Line Comment
     pub(super) fn skip_multi_line_comment(&mut self) -> Kind {
         // If `is_on_new_line` is already set, go directly to faster search which only looks for `*/`
-        if self.token.is_on_new_line() {
-            return self.skip_multi_line_comment_after_line_break(self.source.position());
-        }
+        // We need to identify if comment contains line breaks or not
+        // (`CommentKind::Block` or `CommentKind::MultilineBlock`).
+        // So we have to use the loop below for the first line of the comment even if
+        // `Token`'s `is_on_new_line` flag is already set.
+        // If the loop finds a line break before end of the comment, we then switch to
+        // the faster `skip_multi_line_comment_after_line_break` which searches
+        // for the end of the comment using `memchr`.
 
         byte_search! {
             lexer: self,
@@ -149,6 +154,7 @@ impl<'a> Lexer<'a> {
         self.trivia_builder.add_block_comment(
             self.token.start(),
             self.offset(),
+            CommentKind::Block,
             self.source.whole(),
         );
         Kind::Skip
@@ -170,6 +176,7 @@ impl<'a> Lexer<'a> {
             self.trivia_builder.add_block_comment(
                 self.token.start(),
                 self.offset(),
+                CommentKind::MultilineBlock,
                 self.source.whole(),
             );
             Kind::Skip

crates/oxc_parser/src/lexer/trivia_builder.rs

@@ -59,8 +59,14 @@ impl TriviaBuilder {
         self.add_comment(Comment::new(start, end, CommentKind::Line), source_text);
     }
 
-    pub fn add_block_comment(&mut self, start: u32, end: u32, source_text: &str) {
-        self.add_comment(Comment::new(start, end, CommentKind::Block), source_text);
+    pub fn add_block_comment(
+        &mut self,
+        start: u32,
+        end: u32,
+        kind: CommentKind,
+        source_text: &str,
+    ) {
+        self.add_comment(Comment::new(start, end, kind), source_text);
     }
 
     // For block comments only. This function is not called after line comments because the lexer skips
@@ -425,15 +431,15 @@ token /* Trailing 1 */
         let expected = vec![
             Comment {
                 span: Span::new(1, 13),
-                kind: CommentKind::Block,
+                kind: CommentKind::MultilineBlock,
                 position: CommentPosition::Leading,
                 attached_to: 28,
                 newlines: CommentNewlines::Leading | CommentNewlines::Trailing,
                 content: CommentContent::None,
             },
             Comment {
                 span: Span::new(14, 26),
-                kind: CommentKind::Block,
+                kind: CommentKind::MultilineBlock,
                 position: CommentPosition::Leading,
                 attached_to: 28,
                 newlines: CommentNewlines::Leading | CommentNewlines::Trailing,