feat(ast/estree): add phase field to ImportDeclaration in ESTree AST

.github/actions/clone-submodules/action.yml

@@ -38,4 +38,4 @@ runs:
         show-progress: false
         repository: oxc-project/acorn-test262
         path: tasks/coverage/acorn-test262
-        ref: 4e88e3a36b29e72a4d9b7b77b9bf721915a609aa # Latest main at 7/5/25
+        ref: 2096e67d35f9f9988b186b6a126e489e89ec730b # Latest main at 19/5/25

crates/oxc_ast/src/ast/js.rs

@@ -2396,13 +2396,13 @@ pub struct ImportExpression<'a> {
 #[ast(visit)]
 #[derive(Debug)]
 #[generate_derive(CloneIn, Dummy, TakeIn, GetSpan, GetSpanMut, ContentEq, ESTree)]
+#[estree(field_order(span, specifiers, source, with_clause, phase, import_kind))]
 pub struct ImportDeclaration<'a> {
     pub span: Span,
     /// `None` for `import 'foo'`, `Some([])` for `import {} from 'foo'`
     #[estree(via = ImportDeclarationSpecifiers)]
     pub specifiers: Option<Vec<'a, ImportDeclarationSpecifier<'a>>>,
     pub source: StringLiteral<'a>,
-    #[estree(skip)]
     pub phase: Option<ImportPhase>,
     /// Some(vec![]) for empty assertion
     #[estree(rename = "attributes", via = ImportDeclarationWithClause)]

crates/oxc_ast/src/generated/derive_estree.rs

@@ -1669,6 +1669,7 @@ impl ESTree for ImportDeclaration<'_> {
             "attributes",
             &crate::serialize::js::ImportDeclarationWithClause(self),
         );
+        state.serialize_field("phase", &self.phase);
         state.serialize_ts_field("importKind", &self.import_kind);
         state.end();
     }

justfile

@@ -40,7 +40,7 @@ submodules:
   just clone-submodule tasks/coverage/babel https://github.com/babel/babel.git 578ac4df1c8a05f01350553950dbfbbeaac013c2
   just clone-submodule tasks/coverage/typescript https://github.com/microsoft/TypeScript.git 15392346d05045742e653eab5c87538ff2a3c863
   just clone-submodule tasks/prettier_conformance/prettier https://github.com/prettier/prettier.git 7584432401a47a26943dd7a9ca9a8e032ead7285
-  just clone-submodule tasks/coverage/acorn-test262 https://github.com/oxc-project/acorn-test262 4e88e3a36b29e72a4d9b7b77b9bf721915a609aa
+  just clone-submodule tasks/coverage/acorn-test262 https://github.com/oxc-project/acorn-test262 2096e67d35f9f9988b186b6a126e489e89ec730b
   just update-transformer-fixtures
 
 # Install git pre-commit to format files

napi/parser/README.md

@@ -18,6 +18,9 @@ If you need all ASTs in the same with-TS-properties format, use the `astType: 't
 
 The only differences between Oxc's AST and ESTree / TS-ESTree are:
 
+- Support for Stage 3 ECMA features [`import defer`](https://github.com/tc39/proposal-defer-import-eval)
+  and [`import source`](https://github.com/tc39/proposal-source-phase-imports) on `ImportDeclaration`
+  (not supported on `ImportExpression` yet).
 - Addition of a non-standard `hashbang` field to `Program`.
 
 That aside, the AST should completely align with Acorn's ESTree AST or TS-ESLint's TS-ESTree.

napi/parser/generated/deserialize/js.js

@@ -924,6 +924,7 @@ function deserializeImportDeclaration(pos) {
     specifiers,
     source: deserializeStringLiteral(pos + 32),
     attributes: withClause === null ? [] : withClause.attributes,
+    phase: deserializeOptionImportPhase(pos + 88),
   };
 }
 

napi/parser/generated/deserialize/ts.js

@@ -1071,6 +1071,7 @@ function deserializeImportDeclaration(pos) {
     specifiers,
     source: deserializeStringLiteral(pos + 32),
     attributes: withClause === null ? [] : withClause.attributes,
+    phase: deserializeOptionImportPhase(pos + 88),
     importKind: deserializeImportOrExportKind(pos + 89),
   };
 }

napi/parser/test/parse-raw.test.ts

@@ -125,6 +125,9 @@ describe('JSX', () => {
 // Test raw transfer output matches standard (via JSON) output for edge cases not covered by Test262
 describe('edge cases', () => {
   it.each([
+    // ECMA stage 3
+    'import defer * as ns from "x";',
+    'import source src from "x";',
     // `StringLiteral`s containing lone surrogates and/or lossy replacement characters
     ';"\\uD800\\uDBFF";',
     ';"�\\u{FFFD}";',

napi/parser/test/parse.test.ts

@@ -346,6 +346,118 @@ describe('parse', () => {
       });
     });
 
+    describe('`ImportDeclaration`', () => {
+      describe('import defer', () => {
+        it('ESTree', () => {
+          const ret = parseSync('test.js', 'import defer * as ns from "x";');
+          expect(ret.errors.length).toBe(0);
+          expect(ret.program.body.length).toBe(1);
+          expect(ret.program.body[0]).toEqual({
+            type: 'ImportDeclaration',
+            start: 0,
+            end: 30,
+            specifiers: [
+              {
+                type: 'ImportNamespaceSpecifier',
+                start: 13,
+                end: 20,
+                local: { type: 'Identifier', start: 18, end: 20, name: 'ns' },
+              },
+            ],
+            source: { type: 'Literal', start: 26, end: 29, value: 'x', raw: '"x"' },
+            attributes: [],
+            phase: 'defer',
+          });
+        });
+
+        it('TS-ESTree', () => {
+          const ret = parseSync('test.ts', 'import defer * as ns from "x";');
+          expect(ret.errors.length).toBe(0);
+          expect(ret.program.body.length).toBe(1);
+          expect(ret.program.body[0]).toEqual({
+            type: 'ImportDeclaration',
+            start: 0,
+            end: 30,
+            specifiers: [
+              {
+                type: 'ImportNamespaceSpecifier',
+                start: 13,
+                end: 20,
+                local: {
+                  type: 'Identifier',
+                  start: 18,
+                  end: 20,
+                  decorators: [],
+                  name: 'ns',
+                  optional: false,
+                  typeAnnotation: null,
+                },
+              },
+            ],
+            source: { type: 'Literal', start: 26, end: 29, value: 'x', raw: '"x"' },
+            attributes: [],
+            phase: 'defer',
+            importKind: 'value',
+          });
+        });
+      });
+
+      describe('import source', () => {
+        it('ESTree', () => {
+          const ret = parseSync('test.js', 'import source src from "x";');
+          expect(ret.errors.length).toBe(0);
+          expect(ret.program.body.length).toBe(1);
+          expect(ret.program.body[0]).toEqual({
+            type: 'ImportDeclaration',
+            start: 0,
+            end: 27,
+            specifiers: [
+              {
+                type: 'ImportDefaultSpecifier',
+                start: 14,
+                end: 17,
+                local: { type: 'Identifier', start: 14, end: 17, name: 'src' },
+              },
+            ],
+            source: { type: 'Literal', start: 23, end: 26, value: 'x', raw: '"x"' },
+            attributes: [],
+            phase: 'source',
+          });
+        });
+
+        it('TS-ESTree', () => {
+          const ret = parseSync('test.ts', 'import source src from "x";');
+          expect(ret.errors.length).toBe(0);
+          expect(ret.program.body.length).toBe(1);
+          expect(ret.program.body[0]).toEqual({
+            type: 'ImportDeclaration',
+            start: 0,
+            end: 27,
+            specifiers: [
+              {
+                type: 'ImportDefaultSpecifier',
+                start: 14,
+                end: 17,
+                local: {
+                  type: 'Identifier',
+                  start: 14,
+                  end: 17,
+                  decorators: [],
+                  name: 'src',
+                  optional: false,
+                  typeAnnotation: null,
+                },
+              },
+            ],
+            source: { type: 'Literal', start: 23, end: 26, value: 'x', raw: '"x"' },
+            attributes: [],
+            phase: 'source',
+            importKind: 'value',
+          });
+        });
+      });
+    });
+
     it('lossy replacement character', () => {
       const ret = parseSync('test.js', '`�\\u{FFFD}${x}�\\u{FFFD}`;');
       expect(ret.errors.length).toBe(0);

npm/oxc-types/types.d.ts

@@ -749,6 +749,7 @@ export interface ImportDeclaration extends Span {
   specifiers: Array<ImportDeclarationSpecifier>;
   source: StringLiteral;
   attributes: Array<ImportAttribute>;
+  phase: ImportPhase | null;
   importKind?: ImportOrExportKind;
 }
 

tasks/coverage/snapshots/estree_acorn_jsx.snap

@@ -1,4 +1,4 @@
-commit: 4e88e3a3
+commit: 2096e67d
 
 estree_acorn_jsx Summary:
 AST Parsed     : 39/39 (100.00%)