feat(napi/parser)!: add range option (#11728)

Part of #10307. Add `range` option to `oxc-parser`, to add `range` property to nodes in ESTree AST.

---------

Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>
Co-authored-by: overlookmotel <theoverlookmotel@gmail.com>

Author: 3 people

crates/oxc_allocator/src/boxed.rs

@@ -243,7 +243,7 @@ mod test {
         let allocator = Allocator::default();
         let b = Box::new_in("x", &allocator);
 
-        let mut serializer = CompactTSSerializer::new();
+        let mut serializer = CompactTSSerializer::new(false);
         b.serialize(&mut serializer);
         let s = serializer.into_string();
         assert_eq!(s, r#""x""#);

crates/oxc_allocator/src/vec.rs

@@ -311,7 +311,7 @@ mod test {
         let mut v = Vec::new_in(&allocator);
         v.push("x");
 
-        let mut serializer = CompactTSSerializer::new();
+        let mut serializer = CompactTSSerializer::new(false);
         v.serialize(&mut serializer);
         let s = serializer.into_string();
         assert_eq!(s, r#"["x"]"#);

crates/oxc_ast/src/generated/derive_estree.rs

@@ -47,62 +47,62 @@ const JSON_CAPACITY_RATIO_PRETTY: usize = 80;
 
 impl Program<'_> {
     /// Serialize AST to ESTree JSON, including TypeScript fields.
-    pub fn to_estree_ts_json(&self) -> String {
+    pub fn to_estree_ts_json(&self, ranges: bool) -> String {
         let capacity = self.source_text.len() * JSON_CAPACITY_RATIO_COMPACT;
-        let mut serializer = CompactTSSerializer::with_capacity(capacity);
+        let mut serializer = CompactTSSerializer::with_capacity(capacity, ranges);
         self.serialize(&mut serializer);
         serializer.into_string()
     }
 
     /// Serialize AST to ESTree JSON, without TypeScript fields.
-    pub fn to_estree_js_json(&self) -> String {
+    pub fn to_estree_js_json(&self, ranges: bool) -> String {
         let capacity = self.source_text.len() * JSON_CAPACITY_RATIO_COMPACT;
-        let mut serializer = CompactJSSerializer::with_capacity(capacity);
+        let mut serializer = CompactJSSerializer::with_capacity(capacity, ranges);
         self.serialize(&mut serializer);
         serializer.into_string()
     }
 
     /// Serialize AST to pretty-printed ESTree JSON, including TypeScript fields.
-    pub fn to_pretty_estree_ts_json(&self) -> String {
+    pub fn to_pretty_estree_ts_json(&self, ranges: bool) -> String {
         let capacity = self.source_text.len() * JSON_CAPACITY_RATIO_PRETTY;
-        let mut serializer = PrettyTSSerializer::with_capacity(capacity);
+        let mut serializer = PrettyTSSerializer::with_capacity(capacity, ranges);
         self.serialize(&mut serializer);
         serializer.into_string()
     }
 
     /// Serialize AST to pretty-printed ESTree JSON, without TypeScript fields.
-    pub fn to_pretty_estree_js_json(&self) -> String {
+    pub fn to_pretty_estree_js_json(&self, ranges: bool) -> String {
         let capacity = self.source_text.len() * JSON_CAPACITY_RATIO_PRETTY;
-        let mut serializer = PrettyJSSerializer::with_capacity(capacity);
+        let mut serializer = PrettyJSSerializer::with_capacity(capacity, ranges);
         self.serialize(&mut serializer);
         serializer.into_string()
     }
 
     /// Serialize AST to ESTree JSON, including TypeScript fields, with list of fixes.
-    pub fn to_estree_ts_json_with_fixes(&self) -> String {
+    pub fn to_estree_ts_json_with_fixes(&self, ranges: bool) -> String {
         let capacity = self.source_text.len() * JSON_CAPACITY_RATIO_COMPACT;
-        let serializer = CompactFixesTSSerializer::with_capacity(capacity);
+        let serializer = CompactFixesTSSerializer::with_capacity(capacity, ranges);
         serializer.serialize_with_fixes(self)
     }
 
     /// Serialize AST to ESTree JSON, without TypeScript fields, with list of fixes.
-    pub fn to_estree_js_json_with_fixes(&self) -> String {
+    pub fn to_estree_js_json_with_fixes(&self, ranges: bool) -> String {
         let capacity = self.source_text.len() * JSON_CAPACITY_RATIO_COMPACT;
-        let serializer = CompactFixesJSSerializer::with_capacity(capacity);
+        let serializer = CompactFixesJSSerializer::with_capacity(capacity, ranges);
         serializer.serialize_with_fixes(self)
     }
 
     /// Serialize AST to pretty-printed ESTree JSON, including TypeScript fields, with list of fixes.
-    pub fn to_pretty_estree_ts_json_with_fixes(&self) -> String {
+    pub fn to_pretty_estree_ts_json_with_fixes(&self, ranges: bool) -> String {
         let capacity = self.source_text.len() * JSON_CAPACITY_RATIO_PRETTY;
-        let serializer = PrettyFixesTSSerializer::with_capacity(capacity);
+        let serializer = PrettyFixesTSSerializer::with_capacity(capacity, ranges);
         serializer.serialize_with_fixes(self)
     }
 
     /// Serialize AST to pretty-printed ESTree JSON, without TypeScript fields, with list of fixes.
-    pub fn to_pretty_estree_js_json_with_fixes(&self) -> String {
+    pub fn to_pretty_estree_js_json_with_fixes(&self, ranges: bool) -> String {
         let capacity = self.source_text.len() * JSON_CAPACITY_RATIO_PRETTY;
-        let serializer = PrettyFixesJSSerializer::with_capacity(capacity);
+        let serializer = PrettyFixesJSSerializer::with_capacity(capacity, ranges);
         serializer.serialize_with_fixes(self)
     }
 }
@@ -168,13 +168,17 @@ impl ESTree for ProgramConverter<'_, '_> {
         let span_start =
             if S::INCLUDE_TS_FIELDS { get_ts_start_span(program) } else { program.span.start };
 
+        let ranges = serializer.ranges();
         let mut state = serializer.serialize_struct();
         state.serialize_field("type", &JsonSafeString("Program"));
         state.serialize_field("start", &span_start);
         state.serialize_field("end", &program.span.end);
         state.serialize_field("body", &Concat2(&program.directives, &program.body));
         state.serialize_field("sourceType", &program.source_type.module_kind());
         state.serialize_field("hashbang", &program.hashbang);
+        if ranges {
+            state.serialize_field("range", &[span_start, program.span.end]);
+        }
         state.end();
     }
 }

crates/oxc_ast/src/serialize/mod.rs

@@ -57,7 +57,7 @@ mod tests {
         let cases = [(&"foo", r#""foo""#), (&&"bar", r#""bar""#)];
 
         for (input, output) in cases {
-            let mut serializer = CompactTSSerializer::new();
+            let mut serializer = CompactTSSerializer::new(false);
             input.serialize(&mut serializer);
             let s = serializer.into_string();
             assert_eq!(&s, output);
@@ -69,7 +69,7 @@ mod tests {
         let cases = [(&mut "foo", r#""foo""#), (&mut &mut "bar", r#""bar""#)];
 
         for (input, output) in cases {
-            let mut serializer = CompactTSSerializer::new();
+            let mut serializer = CompactTSSerializer::new(false);
             input.serialize(&mut serializer);
             let s = serializer.into_string();
             assert_eq!(&s, output);
@@ -81,7 +81,7 @@ mod tests {
         let cases = [(None, "null"), (Some(123.0f64), "123")];
 
         for (input, output) in cases {
-            let mut serializer = CompactTSSerializer::new();
+            let mut serializer = CompactTSSerializer::new(false);
             input.serialize(&mut serializer);
             let s = serializer.into_string();
             assert_eq!(&s, output);
@@ -94,7 +94,7 @@ mod tests {
             [(Cow::Borrowed("foo"), r#""foo""#), (Cow::Owned("bar".to_string()), r#""bar""#)];
 
         for (input, output) in cases {
-            let mut serializer = CompactTSSerializer::new();
+            let mut serializer = CompactTSSerializer::new(false);
             input.serialize(&mut serializer);
             let s = serializer.into_string();
             assert_eq!(&s, output);

crates/oxc_estree/src/serialize/blanket.rs

@@ -5,57 +5,88 @@ pub trait Config {
     /// `true` if should record paths to `Literal` nodes that need fixing on JS side
     const FIXES: bool;
 
-    fn new() -> Self;
+    fn new(ranges: bool) -> Self;
+
+    /// Whether to include range information in the serialized output
+    fn ranges(&self) -> bool;
 }
 
-/// Config for serializing AST with TypeScript fields,
-pub struct ConfigTS;
+/// Config for serializing AST with TypeScript fields.
+pub struct ConfigTS {
+    ranges: bool,
+}
 
 impl Config for ConfigTS {
     const INCLUDE_TS_FIELDS: bool = true;
     const FIXES: bool = false;
 
     #[inline(always)]
-    fn new() -> Self {
-        Self
+    fn new(ranges: bool) -> Self {
+        Self { ranges }
+    }
+
+    #[inline(always)]
+    fn ranges(&self) -> bool {
+        self.ranges
     }
 }
 
 /// Config for serializing AST without TypeScript fields.
-pub struct ConfigJS;
+pub struct ConfigJS {
+    ranges: bool,
+}
 
 impl Config for ConfigJS {
     const INCLUDE_TS_FIELDS: bool = false;
     const FIXES: bool = false;
 
     #[inline(always)]
-    fn new() -> Self {
-        Self
+    fn new(ranges: bool) -> Self {
+        Self { ranges }
+    }
+
+    #[inline(always)]
+    fn ranges(&self) -> bool {
+        self.ranges
     }
 }
 
 /// Config for serializing AST with TypeScript fields, with fixes.
-pub struct ConfigFixesTS;
+pub struct ConfigFixesTS {
+    ranges: bool,
+}
 
 impl Config for ConfigFixesTS {
     const INCLUDE_TS_FIELDS: bool = true;
     const FIXES: bool = true;
 
     #[inline(always)]
-    fn new() -> Self {
-        Self
+    fn new(ranges: bool) -> Self {
+        Self { ranges }
+    }
+
+    #[inline(always)]
+    fn ranges(&self) -> bool {
+        self.ranges
     }
 }
 
 /// Config for serializing AST without TypeScript fields, with fixes.
-pub struct ConfigFixesJS;
+pub struct ConfigFixesJS {
+    ranges: bool,
+}
 
 impl Config for ConfigFixesJS {
     const INCLUDE_TS_FIELDS: bool = false;
     const FIXES: bool = true;
 
     #[inline(always)]
-    fn new() -> Self {
-        Self
+    fn new(ranges: bool) -> Self {
+        Self { ranges }
+    }
+
+    #[inline(always)]
+    fn ranges(&self) -> bool {
+        self.ranges
     }
 }

crates/oxc_estree/src/serialize/config.rs

@@ -44,6 +44,8 @@ pub trait Serializer: SerializerPrivate {
     /// Type of sequence serializer this serializer uses.
     type SequenceSerializer: SequenceSerializer;
 
+    fn ranges(&self) -> bool;
+
     /// Serialize struct.
     fn serialize_struct(self) -> Self::StructSerializer;
 
@@ -100,30 +102,29 @@ pub struct ESTreeSerializer<C: Config, F: Formatter> {
     formatter: F,
     trace_path: NonEmptyStack<TracePathPart>,
     fixes_buffer: CodeBuffer,
-    #[expect(unused)]
     config: C,
 }
 
 impl<C: Config, F: Formatter> ESTreeSerializer<C, F> {
     /// Create new [`ESTreeSerializer`].
-    pub fn new() -> Self {
+    pub fn new(ranges: bool) -> Self {
         Self {
             buffer: CodeBuffer::new(),
             formatter: F::new(),
             trace_path: NonEmptyStack::new(TracePathPart::Index(0)),
             fixes_buffer: CodeBuffer::new(),
-            config: C::new(),
+            config: C::new(ranges),
         }
     }
 
     /// Create new [`ESTreeSerializer`] with specified buffer capacity.
-    pub fn with_capacity(capacity: usize) -> Self {
+    pub fn with_capacity(capacity: usize, ranges: bool) -> Self {
         Self {
             buffer: CodeBuffer::with_capacity(capacity),
             formatter: F::new(),
             trace_path: NonEmptyStack::new(TracePathPart::Index(0)),
             fixes_buffer: CodeBuffer::new(),
-            config: C::new(),
+            config: C::new(ranges),
         }
     }
 
@@ -168,7 +169,7 @@ impl<C: Config, F: Formatter> ESTreeSerializer<C, F> {
 impl<C: Config, F: Formatter> Default for ESTreeSerializer<C, F> {
     #[inline(always)]
     fn default() -> Self {
-        Self::new()
+        Self::new(false)
     }
 }
 
@@ -179,6 +180,10 @@ impl<'s, C: Config, F: Formatter> Serializer for &'s mut ESTreeSerializer<C, F>
     type StructSerializer = ESTreeStructSerializer<'s, C, F>;
     type SequenceSerializer = ESTreeSequenceSerializer<'s, C, F>;
 
+    fn ranges(&self) -> bool {
+        self.config.ranges()
+    }
+
     /// Serialize struct.
     #[inline(always)]
     fn serialize_struct(self) -> ESTreeStructSerializer<'s, C, F> {

crates/oxc_estree/src/serialize/mod.rs

@@ -78,7 +78,7 @@ mod tests {
 
     fn run_test<T: ESTree>(cases: &[(T, &str)]) {
         for (input, output) in cases {
-            let mut serializer = CompactTSSerializer::new();
+            let mut serializer = CompactTSSerializer::new(false);
             input.serialize(&mut serializer);
             let s = serializer.into_string();
             assert_eq!(&s, output);

crates/oxc_estree/src/serialize/primitives.rs

@@ -121,12 +121,12 @@ mod tests {
 
         let foo = Foo { none: &[], one: &["one"], two: ["two one", "two two"] };
 
-        let mut serializer = CompactTSSerializer::new();
+        let mut serializer = CompactTSSerializer::new(false);
         foo.serialize(&mut serializer);
         let s = serializer.into_string();
         assert_eq!(&s, r#"{"none":[],"one":["one"],"two":["two one","two two"]}"#);
 
-        let mut serializer = PrettyTSSerializer::new();
+        let mut serializer = PrettyTSSerializer::new(false);
         foo.serialize(&mut serializer);
         let s = serializer.into_string();
         assert_eq!(

crates/oxc_estree/src/serialize/sequences.rs

@@ -483,7 +483,7 @@ mod tests {
         ];
 
         for (input, output) in cases {
-            let mut serializer = CompactTSSerializer::new();
+            let mut serializer = CompactTSSerializer::new(false);
             input.serialize(&mut serializer);
             let s = serializer.into_string();
             assert_eq!(&s, output);
@@ -495,7 +495,7 @@ mod tests {
         let cases = [(String::new(), r#""""#), ("foobar".to_string(), r#""foobar""#)];
 
         for (input, output) in cases {
-            let mut serializer = CompactTSSerializer::new();
+            let mut serializer = CompactTSSerializer::new(false);
             input.to_string().serialize(&mut serializer);
             let s = serializer.into_string();
             assert_eq!(&s, output);
@@ -507,7 +507,7 @@ mod tests {
         let cases = [("", r#""""#), ("a", r#""a""#), ("abc", r#""abc""#)];
 
         for (input, output) in cases {
-            let mut serializer = CompactTSSerializer::new();
+            let mut serializer = CompactTSSerializer::new(false);
             JsonSafeString(input).serialize(&mut serializer);
             let s = serializer.into_string();
             assert_eq!(&s, output);
@@ -530,7 +530,7 @@ mod tests {
         ];
 
         for (input, output) in cases {
-            let mut serializer = CompactTSSerializer::new();
+            let mut serializer = CompactTSSerializer::new(false);
             LoneSurrogatesString(input).serialize(&mut serializer);
             let s = serializer.into_string();
             assert_eq!(&s, output);