feat(syntax): introduce CommentNodeId (#11214)

First step towards #11213.

Introduce `CommentNodeId`, which we'll add to AST structs.

Note: `CommentNodeId` wraps a `u32`, not a `NonMaxU32`. `CommentNodeId`s will be created in parser, every node will have one, and they will never change thereafter. So we don't need to wrap in `Cell<Option<CommentNodeId>>`, the way we do with e.g. `ScopeId`. So `NonMaxU32` offers no benefit here, and would be slightly more costly.

Add a method `get_comment_node_id` to `AstBuilder` which other `AstBuilder` methods will call to populate a field with a `CommentNodeId` field. This method is currently a dummy.

`CommentNodeId` is marked `#[clone_in(default)]`, `#[content_eq(skip)]`, `#[estree(skip)]`, so adding this field to AST types will not disrupt any other code.

Author: overlookmotel

.github/generated/ast_changes_watch_list.yml

@@ -43,6 +43,7 @@ src:
   - 'crates/oxc_span/src/generated/derive_estree.rs'
   - 'crates/oxc_span/src/source_type.rs'
   - 'crates/oxc_span/src/span.rs'
+  - 'crates/oxc_syntax/src/comment_node.rs'
   - 'crates/oxc_syntax/src/generated/assert_layouts.rs'
   - 'crates/oxc_syntax/src/generated/derive_clone_in.rs'
   - 'crates/oxc_syntax/src/generated/derive_content_eq.rs'

crates/oxc_ast/src/ast_builder_impl.rs

@@ -4,7 +4,9 @@ use std::borrow::Cow;
 
 use oxc_allocator::{Allocator, AllocatorAccessor, Box, FromIn, IntoIn, Vec};
 use oxc_span::{Atom, SPAN, Span};
-use oxc_syntax::{number::NumberBase, operator::UnaryOperator, scope::ScopeId};
+use oxc_syntax::{
+    comment_node::CommentNodeId, number::NumberBase, operator::UnaryOperator, scope::ScopeId,
+};
 
 use crate::{AstBuilder, ast::*};
 
@@ -33,6 +35,13 @@ impl<'a> AstBuilder<'a> {
         Self { allocator }
     }
 
+    /// Create [`CommentNodeId`] for an AST node.
+    #[expect(dead_code, clippy::unused_self, clippy::trivially_copy_pass_by_ref)]
+    pub(crate) fn get_comment_node_id(&self) -> CommentNodeId {
+        // TODO: Generate a real ID
+        CommentNodeId::DUMMY
+    }
+
     /// Move a value into the memory arena.
     #[inline]
     pub fn alloc<T>(self, value: T) -> Box<'a, T> {

crates/oxc_ast/src/generated/ast_builder.rs

@@ -3,6 +3,7 @@
 
 //! AST node factories
 
+#![allow(unused_imports)]
 #![expect(
     clippy::default_trait_access,
     clippy::inconsistent_struct_constructor,
@@ -12,7 +13,9 @@
 use std::cell::Cell;
 
 use oxc_allocator::{Allocator, Box, IntoIn, Vec};
-use oxc_syntax::{reference::ReferenceId, scope::ScopeId, symbol::SymbolId};
+use oxc_syntax::{
+    comment_node::CommentNodeId, reference::ReferenceId, scope::ScopeId, symbol::SymbolId,
+};
 
 use crate::ast::*;
 

crates/oxc_ast_macros/src/generated/structs.rs

@@ -0,0 +1,60 @@
+//! Comment Node ID.
+
+use oxc_index::Idx;
+#[cfg(feature = "serialize")]
+use serde::{Serialize, Serializer};
+
+use oxc_allocator::{Allocator, CloneIn, Dummy};
+use oxc_ast_macros::ast;
+
+/// Comment Node ID.
+#[ast]
+#[derive(Debug, Clone, Copy, Eq, PartialEq, Ord, PartialOrd, Hash)]
+#[generate_derive(CloneIn)]
+#[clone_in(default)]
+#[content_eq(skip)]
+#[estree(skip)]
+pub struct CommentNodeId(u32);
+
+impl CommentNodeId {
+    /// Mock comment node ID.
+    ///
+    /// This is used for synthetically-created AST nodes, among other things.
+    pub const DUMMY: Self = CommentNodeId::new(0);
+
+    /// Create `CommentNodeId` from `u32`.
+    pub const fn new(idx: u32) -> Self {
+        Self(idx)
+    }
+}
+
+impl Idx for CommentNodeId {
+    fn from_usize(idx: usize) -> Self {
+        Self(u32::try_from(idx).expect("`idx` is greater than `u32::MAX`"))
+    }
+
+    fn index(self) -> usize {
+        self.0 as usize
+    }
+}
+
+impl Default for CommentNodeId {
+    #[inline]
+    fn default() -> Self {
+        Self::DUMMY
+    }
+}
+
+impl<'a> Dummy<'a> for CommentNodeId {
+    #[inline]
+    fn dummy(_allocator: &'a Allocator) -> Self {
+        Self::DUMMY
+    }
+}
+
+#[cfg(feature = "serialize")]
+impl Serialize for CommentNodeId {
+    fn serialize<S: Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
+        serializer.serialize_u32(self.0)
+    }
+}

crates/oxc_syntax/src/comment_node.rs

@@ -7,14 +7,20 @@ use std::mem::{align_of, offset_of, size_of};
 
 use nonmax::NonMaxU32;
 
-use crate::{module_record::*, number::*, operator::*, reference::*, scope::*, symbol::*};
+use crate::{
+    comment_node::*, module_record::*, number::*, operator::*, reference::*, scope::*, symbol::*,
+};
 
 #[cfg(target_pointer_width = "64")]
 const _: () = {
     // Padding: 0 bytes
     assert!(size_of::<NonMaxU32>() == 4);
     assert!(align_of::<NonMaxU32>() == 4);
 
+    // Padding: 0 bytes
+    assert!(size_of::<CommentNodeId>() == 4);
+    assert!(align_of::<CommentNodeId>() == 4);
+
     // Padding: 0 bytes
     assert!(size_of::<NameSpan>() == 24);
     assert!(align_of::<NameSpan>() == 8);
@@ -99,6 +105,10 @@ const _: () = {
     assert!(size_of::<NonMaxU32>() == 4);
     assert!(align_of::<NonMaxU32>() == 4);
 
+    // Padding: 0 bytes
+    assert!(size_of::<CommentNodeId>() == 4);
+    assert!(align_of::<CommentNodeId>() == 4);
+
     // Padding: 0 bytes
     assert!(size_of::<NameSpan>() == 16);
     assert!(align_of::<NameSpan>() == 4);

crates/oxc_syntax/src/generated/assert_layouts.rs

@@ -5,9 +5,22 @@
 
 use oxc_allocator::{Allocator, CloneIn};
 
+use crate::comment_node::*;
 use crate::number::*;
 use crate::operator::*;
 
+impl<'new_alloc> CloneIn<'new_alloc> for CommentNodeId {
+    type Cloned = CommentNodeId;
+
+    fn clone_in(&self, allocator: &'new_alloc Allocator) -> Self::Cloned {
+        Default::default()
+    }
+
+    fn clone_in_with_semantic_ids(&self, allocator: &'new_alloc Allocator) -> Self::Cloned {
+        Default::default()
+    }
+}
+
 impl<'new_alloc> CloneIn<'new_alloc> for NumberBase {
     type Cloned = NumberBase;
 

crates/oxc_syntax/src/generated/derive_clone_in.rs

@@ -6,6 +6,7 @@ use std::num::NonZeroU32;
 use oxc_ast_macros::ast;
 
 pub mod class;
+pub mod comment_node;
 pub mod es_target;
 pub mod identifier;
 pub mod keyword;

crates/oxc_syntax/src/lib.rs

@@ -112,6 +112,7 @@ export default function generateAncestorsCode(types) {
   }
 
   return `
+    #![allow(unused_imports)]
     #![expect(
       clippy::cast_ptr_alignment,
       clippy::elidable_lifetime_names,
@@ -124,7 +125,7 @@ export default function generateAncestorsCode(types) {
 
     use oxc_allocator::{Address, Box, GetAddress, Vec};
     use oxc_ast::ast::*;
-    use oxc_syntax::scope::ScopeId;
+    use oxc_syntax::{comment_node::CommentNodeId, scope::ScopeId};
 
     /// Type of [\`Ancestor\`].
     /// Used in [\`crate::TraverseCtx::retag_stack\`].

crates/oxc_traverse/scripts/lib/ancestor.mjs

@@ -2,6 +2,7 @@
 // Generated by `oxc_traverse/scripts/build.mjs`.
 // To alter this generated file you have to edit the codegen.
 
+#![allow(unused_imports)]
 #![expect(
     clippy::cast_ptr_alignment,
     clippy::elidable_lifetime_names,
@@ -14,7 +15,7 @@ use std::{cell::Cell, marker::PhantomData, mem::offset_of};
 
 use oxc_allocator::{Address, Box, GetAddress, Vec};
 use oxc_ast::ast::*;
-use oxc_syntax::scope::ScopeId;
+use oxc_syntax::{comment_node::CommentNodeId, scope::ScopeId};
 
 /// Type of [`Ancestor`].
 /// Used in [`crate::TraverseCtx::retag_stack`].

crates/oxc_traverse/src/generated/ancestor.rs

@@ -620,7 +620,7 @@ fn template(krate: &str, assertions_64: &TokenStream, assertions_32: &TokenStrea
             use nonmax::NonMaxU32;
 
             ///@@line_break
-            use crate::{module_record::*, number::*, operator::*, reference::*, scope::*, symbol::*};
+            use crate::{comment_node::*, module_record::*, number::*, operator::*, reference::*, scope::*, symbol::*};
         },
         "napi/parser" => quote! {
             use crate::raw_transfer_types::*;