fix(parser): attach legal comments to following token (#21670)

Dunqing · Dunqing · commit aaabde457451 · 2026-04-29T14:16:53.000Z
## Summary - treat `Legal` and `JsdocLegal` comments as leading comments for the following token instead of allowing them to become trailing comments on the previous token - apply that rule to both legal block comments and legal line comments after code - add parser regressions for both cases and a codegen idempotency regression for comment-preserving minify mode ## Why `monitor-oxc` whitespace found a repeated print/parse instability in comment-preserving whitespace removal. Some bundled files contain legal comments such as `@license`/`@preserve` or `/*! ... */` between two statements. After one print, Oxc could produce a shape where a legal comment appeared after code and before the next token. On the second parse, the trivia builder sometimes classified that legal comment as trailing trivia for the previous token. That classification is wrong for legal-comment preservation. Oxc only treats legal comments as preservable legal comments when they are leading comments. So the parser should keep legal comments attachable to the following token instead of finalizing them as trailing comments. This makes repeated parse/print cycles stable in modes that remove whitespace but keep comments, without changing executable JavaScript semantics. Ordinary non-legal comments still use the existing leading/trailing classification. ## esbuild comparison I checked esbuild's implementation because Oxc's legal-comment behavior is intended to follow the same model. esbuild's lexer records legal comments in `LegalCommentsBeforeToken`, and the parser consumes that list before parsing the next statement by inserting `SComment { IsLegalComment: true }` statements. In other words, esbuild models legal comments as comments before the next token/statement, not as trailing trivia attached to the previous token. For the concrete repro, esbuild with `minify: true` and `legalComments: "inline"` keeps the legal comments inline and is idempotent across repeated transforms: ```js foo();/** * @license MIT **//*! #__NO_SIDE_EFFECTS__ */function bar(){} ``` The key invariant from esbuild is not the exact newline placement. It is that legal comments remain associated with the following statement/token for preservation. This change moves Oxc's parser classification toward that invariant while leaving ordinary non-legal trailing comments alone. ## Testing - `cargo test -p oxc_parser trivia_builder -- --nocapture` - `cargo test -p oxc_codegen comments -- --nocapture` - `cargo fmt --all --check` - `git diff --check` - `monitor-oxc whitespace` filtered to the two previously failing files (`@vue-macros/devtools` and `@asamuzakjp/css-color`): both files were collected and processed with no `RemoveWhitespace` diagnostics. The local runtime phase then failed separately under Node.js v25.8.1 on old package imports.
diff --git a/crates/oxc_codegen/tests/integration/comments.rs b/crates/oxc_codegen/tests/integration/comments.rs
@@ -1,5 +1,5 @@
 use crate::{
-    test_idempotency,
+    test_idempotency, test_idempotency_options,
     tester::{test, test_same},
 };
 
@@ -652,3 +652,20 @@ function foo() {
 fn test_pure_comment_on_object_idempotency() {
     test_idempotency("export const X = /* @__PURE__ */ { a: 1 };");
 }
+
+#[test]
+fn test_legal_comment_after_code_minify_with_comments_idempotency() {
+    use oxc_codegen::{CodegenOptions, CommentOptions};
+
+    test_idempotency_options(
+        "foo();/**
+* @license MIT
+**//*! #__NO_SIDE_EFFECTS__ */function bar(){}",
+        &CodegenOptions {
+            minify: true,
+            comments: CommentOptions::default(),
+            source_map_path: Some("test.js".into()),
+            ..CodegenOptions::default()
+        },
+    );
+}
diff --git a/crates/oxc_codegen/tests/integration/tester.rs b/crates/oxc_codegen/tests/integration/tester.rs
@@ -107,16 +107,21 @@ pub fn codegen_options(source_text: &str, options: &CodegenOptions) -> CodegenRe
 
 #[track_caller]
 pub fn test_idempotency(source_text: &str) {
+    test_idempotency_options(source_text, &default_options());
+}
+
+#[track_caller]
+pub fn test_idempotency_options(source_text: &str, options: &CodegenOptions) {
     let allocator = Allocator::default();
     let source_type = SourceType::tsx();
     let ret = Parser::new(&allocator, source_text, source_type).parse();
     assert!(ret.errors.is_empty(), "Parse errors: {:?}", ret.errors);
-    let first = Codegen::new().with_options(default_options()).build(&ret.program).code;
+    let first = Codegen::new().with_options(options.clone()).build(&ret.program).code;
 
     let allocator2 = Allocator::default();
     let ret2 = Parser::new(&allocator2, &first, source_type).parse();
     assert!(ret2.errors.is_empty(), "Parse errors on second pass: {:?}", ret2.errors);
-    let second = Codegen::new().with_options(default_options()).build(&ret2.program).code;
+    let second = Codegen::new().with_options(options.clone()).build(&ret2.program).code;
 
     assert_eq!(
         first, second,
diff --git a/crates/oxc_parser/src/lexer/trivia_builder.rs b/crates/oxc_parser/src/lexer/trivia_builder.rs
@@ -95,8 +95,9 @@ impl<'a> TriviaBuilder<'a> {
         // The last unprocessed comment is on a newline.
         let len = self.comments.len();
         if self.processed < len {
-            self.comments[len - 1].set_followed_by_newline(true);
-            if !self.saw_newline {
+            let comment = &mut self.comments[len - 1];
+            comment.set_followed_by_newline(true);
+            if !self.saw_newline && !Self::should_stay_leading(comment) {
                 self.processed = self.comments.len();
             }
         }
@@ -148,6 +149,11 @@ impl<'a> TriviaBuilder<'a> {
         !self.saw_newline && !matches!(self.previous_kind, Kind::Eq | Kind::LParen)
     }
 
+    fn should_stay_leading(comment: &Comment) -> bool {
+        // Match esbuild's model where legal comments are preserved before the following token/statement.
+        matches!(comment.content, CommentContent::Legal | CommentContent::JsdocLegal)
+    }
+
     /// Update `pure_comment` / `has_no_side_effects_comment` to point to the comment at `index`.
     fn set_annotation_flags(&mut self, comment: &Comment, index: usize) {
         if comment.is_pure() {
@@ -177,7 +183,8 @@ impl<'a> TriviaBuilder<'a> {
         if comment.is_line() {
             // A line comment is always followed by a newline. This is never set in `handle_newline`.
             comment.set_followed_by_newline(true);
-            if self.should_be_treated_as_trailing_comment() {
+            if self.should_be_treated_as_trailing_comment() && !Self::should_stay_leading(&comment)
+            {
                 self.processed = self.comments.len() + 1; // +1 to include this comment.
             }
             self.saw_newline = true;
@@ -502,6 +509,35 @@ token /* Trailing 1 */
         assert_eq!(comments, expected);
     }
 
+    #[test]
+    fn legal_comment_after_code_is_attached_to_next_token() {
+        let source_text = "foo();/**
+ * @license MIT
+ **/
+function bar() {}";
+        let comments = get_comments(source_text);
+        let function_start = u32::try_from(source_text.find("function").unwrap()).unwrap();
+
+        assert_eq!(comments.len(), 1);
+        assert_eq!(comments[0].position, CommentPosition::Leading);
+        assert_eq!(comments[0].attached_to, function_start);
+        assert!(comments[0].is_legal());
+        assert!(comments[0].followed_by_newline());
+    }
+
+    #[test]
+    fn legal_line_comment_after_code_is_attached_to_next_token() {
+        let source_text = "foo();//! @license MIT\nfunction bar() {}";
+        let comments = get_comments(source_text);
+        let function_start = u32::try_from(source_text.find("function").unwrap()).unwrap();
+
+        assert_eq!(comments.len(), 1);
+        assert_eq!(comments[0].position, CommentPosition::Leading);
+        assert_eq!(comments[0].attached_to, function_start);
+        assert!(comments[0].is_legal());
+        assert!(comments[0].followed_by_newline());
+    }
+
     #[test]
     fn leading_comments_after_eq() {
         let source_text = "
