feat(napi/parser): add option to add parent prop to AST nodes with raw transfer (#14344)

Add an option to `oxc-parser` to add `parent` to all AST nodes. This option is only available with raw transfer (not really feasible with JSON transfer, as JSON doesn't support circular references).

This is really for the purposes of JS plugins in Oxlint, so have not included the new deserializers which add `parent` in the `oxc-parser` NPM package, to avoid bloating download size. But it's ideal home is in `napi/parser` so can add it to the conformance tests.

`parent` is correct for all nodes in all Test262 and TypeScript test cases.

Author: overlookmotel

.github/generated/ast_changes_watch_list.yml

@@ -68,10 +68,14 @@ src:
   - 'crates/oxc_traverse/src/generated/scopes_collector.rs'
   - 'napi/parser/generated/constants.js'
   - 'napi/parser/generated/deserialize/js.js'
+  - 'napi/parser/generated/deserialize/js_parent.js'
   - 'napi/parser/generated/deserialize/js_range.js'
+  - 'napi/parser/generated/deserialize/js_range_parent.js'
   - 'napi/parser/generated/deserialize/ts.js'
+  - 'napi/parser/generated/deserialize/ts_parent.js'
   - 'napi/parser/generated/deserialize/ts_range.js'
   - 'napi/parser/generated/deserialize/ts_range_no_parens.js'
+  - 'napi/parser/generated/deserialize/ts_range_parent.js'
   - 'napi/parser/generated/lazy/constructors.js'
   - 'napi/parser/generated/lazy/types.js'
   - 'napi/parser/generated/lazy/walk.js'

.github/workflows/ci.yml

@@ -196,7 +196,7 @@ jobs:
       - if: steps.filter.outputs.src == 'true'
         name: Run tests in workspace
         env:
-          RUN_RAW_TESTS: "true"
+          RUN_RAW_RANGE_TESTS: "true"
         run: |
           rustup target add wasm32-wasip1-threads
           pnpm run build-test

crates/oxc_ast/src/serialize/js.rs

@@ -20,8 +20,11 @@ use super::{EmptyArray, Null};
 #[estree(raw_deser = "
     const pattern = DESER[BindingPatternKind](POS_OFFSET.kind);
     if (IS_TS) {
+        const previousParent = parent;
+        parent = pattern;
         pattern.optional = DESER[bool](POS_OFFSET.optional);
         pattern.typeAnnotation = DESER[Option<Box<TSTypeAnnotation>>](POS_OFFSET.type_annotation);
+        if (PARENT) parent = previousParent;
     }
     pattern
 ")]
@@ -119,22 +122,31 @@ impl ESTree for CatchParameterConverter<'_, '_> {
         const params = DESER[Vec<FormalParameter>](POS_OFFSET.items);
         if (uint32[(POS_OFFSET.rest) >> 2] !== 0 && uint32[(POS_OFFSET.rest + 4) >> 2] !== 0) {
             pos = uint32[(POS_OFFSET.rest) >> 2];
+
             let start, end;
-            params.push({
+            const previousParent = parent;
+            const rest = parent = {
                 type: 'RestElement',
                 ...(IS_TS && { decorators: [] }),
-                argument: DESER[BindingPatternKind]( POS_OFFSET<BindingRestElement>.argument.kind ),
+                argument: null,
                 ...(IS_TS && {
                     optional: DESER[bool]( POS_OFFSET<BindingRestElement>.argument.optional ),
-                    typeAnnotation: DESER[Option<Box<TSTypeAnnotation>>](
-                        POS_OFFSET<BindingRestElement>.argument.type_annotation
-                    ),
+                    typeAnnotation: null,
                     value: null,
                 }),
                 start: start = DESER[u32]( POS_OFFSET<BindingRestElement>.span.start ),
                 end: end = DESER[u32]( POS_OFFSET<BindingRestElement>.span.end ),
                 ...(RANGE && { range: [start, end] }),
-            });
+                ...(PARENT && { parent }),
+            };
+            rest.argument = DESER[BindingPatternKind]( POS_OFFSET<BindingRestElement>.argument.kind );
+            if (IS_TS) {
+                rest.typeAnnotation = DESER[Option<Box<TSTypeAnnotation>>](
+                    POS_OFFSET<BindingRestElement>.argument.type_annotation
+                );
+            }
+            params.push(rest);
+            if (PARENT) parent = previousParent;
         }
         params
     "
@@ -187,27 +199,32 @@ impl ESTree for FormalParametersRest<'_, '_> {
         if (IS_TS) {
             const accessibility = DESER[Option<TSAccessibility>](POS_OFFSET.accessibility),
                 readonly = DESER[bool](POS_OFFSET.readonly),
-                override = DESER[bool](POS_OFFSET.override);
+                override = DESER[bool](POS_OFFSET.override),
+                previousParent = parent;
             if (accessibility === null && !readonly && !override) {
-                param = DESER[BindingPatternKind](POS_OFFSET.pattern.kind);
+                param = parent = DESER[BindingPatternKind](POS_OFFSET.pattern.kind);
                 param.decorators = DESER[Vec<Decorator>](POS_OFFSET.decorators);
                 param.optional = DESER[bool](POS_OFFSET.pattern.optional);
                 param.typeAnnotation = DESER[Option<Box<TSTypeAnnotation>>](POS_OFFSET.pattern.type_annotation);
             } else {
                 let start, end;
-                param = {
+                param = parent = {
                     type: 'TSParameterProperty',
                     accessibility,
-                    decorators: DESER[Vec<Decorator>](POS_OFFSET.decorators),
+                    decorators: null,
                     override,
-                    parameter: DESER[BindingPattern](POS_OFFSET.pattern),
+                    parameter: null,
                     readonly,
                     static: false,
                     start: start = DESER[u32]( POS_OFFSET<BindingRestElement>.span.start ),
                     end: end = DESER[u32]( POS_OFFSET<BindingRestElement>.span.end ),
                     ...(RANGE && { range: [start, end] }),
+                    ...(PARENT && { parent }),
                 };
+                param.decorators = DESER[Vec<Decorator>](POS_OFFSET.decorators);
+                param.parameter = DESER[BindingPattern](POS_OFFSET.pattern);
             }
+            if (PARENT) parent = previousParent;
         } else {
             param = DESER[BindingPatternKind](POS_OFFSET.pattern.kind);
         }
@@ -384,7 +401,11 @@ impl ESTree for ExportAllDeclarationWithClause<'_, '_> {
     ts_type = "FunctionBody | Expression",
     raw_deser = "
         let body = DESER[Box<FunctionBody>](POS_OFFSET.body);
-        THIS.expression ? body.body[0].expression : body
+        if (THIS.expression === true) {
+            body = body.body[0].expression;
+            if (PARENT) body.parent = parent;
+        }
+        body
     "
 )]
 pub struct ArrowFunctionExpressionBody<'a>(pub &'a ArrowFunctionExpression<'a>);
@@ -405,23 +426,31 @@ impl ESTree for ArrowFunctionExpressionBody<'_> {
 #[estree(
     ts_type = "IdentifierReference | AssignmentTargetWithDefault",
     raw_deser = "
-        const init = DESER[Option<Expression>](POS_OFFSET.init),
-            keyCopy = { ...THIS.key },
-            value = init === null
-                ? keyCopy
-                : {
-                    type: 'AssignmentPattern',
-                    ...(IS_TS && { decorators: [] }),
-                    left: keyCopy,
-                    right: init,
-                    ...(IS_TS && {
-                        optional: false,
-                        typeAnnotation: null,
-                    }),
-                    start: THIS.start,
-                    end: THIS.end,
-                    ...(RANGE && { range: [THIS.start, THIS.end] }),
-                };
+        const init = DESER[Option<Expression>](POS_OFFSET.init);
+        let value = { ...THIS.key };
+        if (init !== null) {
+            const left = value;
+            const previousParent = parent;
+            value = parent = {
+                type: 'AssignmentPattern',
+                ...(IS_TS && { decorators: [] }),
+                left,
+                right: init,
+                ...(IS_TS && {
+                    optional: false,
+                    typeAnnotation: null,
+                }),
+                start: THIS.start,
+                end: THIS.end,
+                ...(RANGE && { range: [THIS.start, THIS.end] }),
+                ...(PARENT && { parent }),
+            };
+            if (PARENT) {
+                left.parent = value;
+                init.parent = value;
+                parent = previousParent;
+            }
+        }
         value
     "
 )]
@@ -458,16 +487,22 @@ impl ESTree for AssignmentTargetPropertyIdentifierInit<'_> {
 /// ESTree implementation is unchanged from the auto-generated version.
 #[ast_meta]
 #[estree(raw_deser = "
-    let node = DESER[Expression](POS_OFFSET.expression);
+    let node;
     if (PRESERVE_PARENS) {
         let start, end;
-        node = {
+        const previousParent = parent;
+        node = parent = {
             type: 'ParenthesizedExpression',
-            expression: node,
+            expression: null,
             start: start = DESER[u32]( POS_OFFSET.span.start ),
             end: end = DESER[u32]( POS_OFFSET.span.end ),
             ...(RANGE && { range: [start, end] }),
+            ...(PARENT && { parent }),
         };
+        node.expression = DESER[Expression](POS_OFFSET.expression);
+        if (PARENT) parent = previousParent;
+    } else {
+        node = DESER[Expression](POS_OFFSET.expression);
     }
     node
 ")]

crates/oxc_ast/src/serialize/jsx.rs

@@ -56,7 +56,7 @@ impl ESTree for JSXOpeningElementSelfClosing<'_, '_> {
     ts_type = "JSXIdentifier",
     raw_deser = "
         const ident = DESER[Box<IdentifierReference>](POS);
-        { type: 'JSXIdentifier', name: ident.name, start: ident.start, end: ident.end, ...(RANGE && { range: ident.range }) }
+        { type: 'JSXIdentifier', name: ident.name, start: ident.start, end: ident.end, ...(RANGE && { range: ident.range }), ...(PARENT && { parent }) }
     "
 )]
 pub struct JSXElementIdentifierReference<'a, 'b>(pub &'b IdentifierReference<'a>);
@@ -75,7 +75,7 @@ impl ESTree for JSXElementIdentifierReference<'_, '_> {
     ts_type = "JSXIdentifier",
     raw_deser = "
         const thisExpr = DESER[Box<ThisExpression>](POS);
-        { type: 'JSXIdentifier', name: 'this', start: thisExpr.start, end: thisExpr.end, ...(RANGE && { range: thisExpr.range }) }
+        { type: 'JSXIdentifier', name: 'this', start: thisExpr.start, end: thisExpr.end, ...(RANGE && { range: thisExpr.range }), ...(PARENT && { parent }) }
     "
 )]
 pub struct JSXElementThisExpression<'b>(pub &'b ThisExpression);

crates/oxc_ast/src/serialize/literal.rs

@@ -202,7 +202,7 @@ impl ESTree for RegExpFlagsConverter<'_> {
         value.cooked = value.cooked
             .replace(/\uFFFD(.{4})/g, (_, hex) => String.fromCodePoint(parseInt(hex, 16)));
     }
-    { type: 'TemplateElement', value, tail, start, end, ...(RANGE && { range: [start, end] }) }
+    { type: 'TemplateElement', value, tail, start, end, ...(RANGE && { range: [start, end] }), ...(PARENT && { parent }) }
 "#)]
 pub struct TemplateElementConverter<'a, 'b>(pub &'b TemplateElement<'a>);
 

crates/oxc_ast/src/serialize/mod.rs

@@ -121,13 +121,27 @@ impl Program<'_> {
 /// `Program` span start is 0 (not 5).
 #[ast_meta]
 #[estree(raw_deser = "
-    const body = DESER[Vec<Directive>](POS_OFFSET.directives);
-    body.push(...DESER[Vec<Statement>](POS_OFFSET.body));
+    const start = IS_TS ? 0 : DESER[u32](POS_OFFSET.span.start),
+        end = DESER[u32](POS_OFFSET.span.end);
+
+    const program = parent = {
+        type: 'Program',
+        body: null,
+        sourceType: DESER[ModuleKind](POS_OFFSET.source_type.module_kind),
+        hashbang: null,
+        start,
+        end,
+        ...(RANGE && { range: [start, end] }),
+        ...(PARENT && { parent: null }),
+    };
 
-    const end = DESER[u32](POS_OFFSET.span.end);
+    program.hashbang = DESER[Option<Hashbang>](POS_OFFSET.hashbang);
+
+    const body = program.body = DESER[Vec<Directive>](POS_OFFSET.directives);
+    body.push(...DESER[Vec<Statement>](POS_OFFSET.body));
 
-    let start;
     if (IS_TS) {
+        let start;
         if (body.length > 0) {
             const first = body[0];
             start = first.start;
@@ -144,19 +158,16 @@ impl Program<'_> {
         } else {
             start = end;
         }
-    } else {
-        start = DESER[u32](POS_OFFSET.span.start);
+
+        if (RANGE) {
+            program.start = program.range[0] = start;
+        } else {
+            program.start = start;
+        }
     }
 
-    const program = {
-        type: 'Program',
-        body,
-        sourceType: DESER[ModuleKind](POS_OFFSET.source_type.module_kind),
-        hashbang: DESER[Option<Hashbang>](POS_OFFSET.hashbang),
-        start,
-        end,
-        ...(RANGE && { range: [start, end] }),
-    };
+    if (PARENT) parent = null;
+
     program
 ")]
 pub struct ProgramConverter<'a, 'b>(pub &'b Program<'a>);