fix(ast)!: add TSGlobalDeclaration type (#15712)

Fix #14860.

### The problem

`TSModuleDeclaration` type was used to represent 4 different syntaxes:

* `namespace X {}`
* `module X {}`
* `module "x" {}`
* `global {}`

(and all the above prefixed with `declare`)

`global {}` is quite different from the others in a few ways:

* It has no identifier (`global` is a keyword, not an identifier).
* It has no symbol.
* The `body` block is not optional.
* Directives are not allowed in the `body` block.
* It is always ambient context (regardless of whether it has `declare` modifier).

In particular, it was causing panics because `symbol_id` field for `TSModuleDeclaration`s representing `global {}` was `None`.

### Solution

Rather than trying to make `TSModuleDeclaration` type encode all these differences, and make Oxc's code reason about them, split `global {}` into a new type `TSGlobalDeclaration`.

The rest of the diff is just adjusting code to also handle `TSGlobalDeclaration` where it was dealing with `TSModuleDeclaration`s.

This change simplifies the parser quite a bit.

`oxc_semantic`'s `SymbolDeclarationTest` tester now tests that all `TSModuleDeclaration`s with `id: BindingIdentifier` do have a symbol:

https://github.com/oxc-project/oxc/pull/15712/files#diff-ce544d71b839faa898887ac920237e563e59a708e7fca86b53023498ab67a611L101-R110

### Formatter bug

There is one regression in the formatter for `typescript/module/global.ts` case.

https://github.com/oxc-project/oxc/pull/15712/files#diff-f248b1d49b8c482864810055632d7322cdebc895dd4dfe05fbefcf5e23ba12c9R51

Input:

```ts
declare /* module */ global {}
declare /* namespace */ global {}
```

Output:

```diff
- declare /* module */ global {}
- declare /* namespace */ global {}
+ declare global /* module */ {}
+ declare global /* namespace */ {}
```

I assume this is happening because there's no longer a `BindingIdentifier` for the `global` keyword for the comment to get attached to.

I am not sure how to fix this. Maybe the `global_span` field can help?

@Dunqing This PR touches a *lot* of files. Can I propose that we merge it before it gets conflicts, and if you can give me some guidance, I'll do a follow-up PR to fix it?

Author: overlookmotel

apps/oxlint/src-js/generated/deserialize.js

@@ -1458,6 +1458,8 @@ function deserializeStatement(pos) {
     case 38:
       return deserializeBoxTSModuleDeclaration(pos + 8);
     case 39:
+      return deserializeBoxTSGlobalDeclaration(pos + 8);
+    case 40:
       return deserializeBoxTSImportEqualsDeclaration(pos + 8);
     case 64:
       return deserializeBoxImportDeclaration(pos + 8);
@@ -1544,6 +1546,8 @@ function deserializeDeclaration(pos) {
     case 38:
       return deserializeBoxTSModuleDeclaration(pos + 8);
     case 39:
+      return deserializeBoxTSGlobalDeclaration(pos + 8);
+    case 40:
       return deserializeBoxTSImportEqualsDeclaration(pos + 8);
     default:
       throw Error(`Unexpected discriminant ${uint8[pos]} for Declaration`);
@@ -4933,7 +4937,6 @@ function deserializeTSTypePredicateName(pos) {
 
 function deserializeTSModuleDeclaration(pos) {
   let kind = deserializeTSModuleDeclarationKind(pos + 84),
-    global = kind === 'global',
     start = deserializeU32(pos),
     end = deserializeU32(pos + 4),
     declare = deserializeBool(pos + 85),
@@ -4947,7 +4950,7 @@ function deserializeTSModuleDeclaration(pos) {
       id: null,
       kind,
       declare,
-      global,
+      global: false,
       start,
       end,
       range: [start, end],
@@ -4962,7 +4965,7 @@ function deserializeTSModuleDeclaration(pos) {
       body,
       kind,
       declare,
-      global,
+      global: false,
       start,
       end,
       range: [start, end],
@@ -5031,10 +5034,8 @@ function deserializeTSModuleDeclaration(pos) {
 function deserializeTSModuleDeclarationKind(pos) {
   switch (uint8[pos]) {
     case 0:
-      return 'global';
-    case 1:
       return 'module';
-    case 2:
+    case 1:
       return 'namespace';
     default:
       throw Error(`Unexpected discriminant ${uint8[pos]} for TSModuleDeclarationKind`);
@@ -5063,6 +5064,44 @@ function deserializeTSModuleDeclarationBody(pos) {
   }
 }
 
+function deserializeTSGlobalDeclaration(pos) {
+  let start = deserializeU32(pos),
+    end = deserializeU32(pos + 4),
+    previousParent = parent,
+    node = (parent = {
+      __proto__: NodeProto,
+      type: 'TSModuleDeclaration',
+      id: null,
+      body: null,
+      kind: null,
+      declare: deserializeBool(pos + 76),
+      global: null,
+      start,
+      end,
+      range: [start, end],
+      parent,
+    }),
+    keywordStart,
+    keywordEnd;
+  node.id = {
+    __proto__: NodeProto,
+    type: 'Identifier',
+    decorators: [],
+    name: 'global',
+    optional: false,
+    typeAnnotation: null,
+    start: (keywordStart = deserializeU32(pos + 8)),
+    end: (keywordEnd = deserializeU32(pos + 12)),
+    range: [keywordStart, keywordEnd],
+    parent,
+  };
+  node.body = deserializeTSModuleBlock(pos + 16);
+  node.kind = 'global';
+  node.global = true;
+  parent = previousParent;
+  return node;
+}
+
 function deserializeTSModuleBlock(pos) {
   let start = deserializeU32(pos),
     end = deserializeU32(pos + 4),
@@ -6257,6 +6296,10 @@ function deserializeBoxTSModuleDeclaration(pos) {
   return deserializeTSModuleDeclaration(uint32[pos >> 2]);
 }
 
+function deserializeBoxTSGlobalDeclaration(pos) {
+  return deserializeTSGlobalDeclaration(uint32[pos >> 2]);
+}
+
 function deserializeBoxTSImportEqualsDeclaration(pos) {
   return deserializeTSImportEqualsDeclaration(uint32[pos >> 2]);
 }

apps/oxlint/src-js/generated/types.d.ts

@@ -432,6 +432,7 @@ export type Declaration =
   | TSInterfaceDeclaration
   | TSEnumDeclaration
   | TSModuleDeclaration
+  | TSGlobalDeclaration
   | TSImportEqualsDeclaration;
 
 export interface VariableDeclaration extends Span {
@@ -1479,11 +1480,21 @@ export interface TSModuleDeclaration extends Span {
   body: TSModuleBlock | null;
   kind: TSModuleDeclarationKind;
   declare: boolean;
-  global: boolean;
+  global: false;
   parent: Node;
 }
 
-export type TSModuleDeclarationKind = 'global' | 'module' | 'namespace';
+export type TSModuleDeclarationKind = 'module' | 'namespace';
+
+export interface TSGlobalDeclaration extends Span {
+  type: 'TSModuleDeclaration';
+  id: IdentifierName;
+  body: TSModuleBlock;
+  kind: 'global';
+  declare: boolean;
+  global: true;
+  parent: Node;
+}
 
 export interface TSModuleBlock extends Span {
   type: 'TSModuleBlock';
@@ -1865,6 +1876,7 @@ export type Node =
   | TSInterfaceHeritage
   | TSTypePredicate
   | TSModuleDeclaration
+  | TSGlobalDeclaration
   | TSModuleBlock
   | TSTypeLiteral
   | TSInferType

apps/oxlint/src-js/generated/visitor.d.ts

@@ -330,8 +330,8 @@ export interface VisitorObject {
   'TSMethodSignature:exit'?: (node: ESTree.TSMethodSignature) => void;
   TSModuleBlock?: (node: ESTree.TSModuleBlock) => void;
   'TSModuleBlock:exit'?: (node: ESTree.TSModuleBlock) => void;
-  TSModuleDeclaration?: (node: ESTree.TSModuleDeclaration) => void;
-  'TSModuleDeclaration:exit'?: (node: ESTree.TSModuleDeclaration) => void;
+  TSModuleDeclaration?: (node: ESTree.TSModuleDeclaration | ESTree.TSGlobalDeclaration) => void;
+  'TSModuleDeclaration:exit'?: (node: ESTree.TSModuleDeclaration | ESTree.TSGlobalDeclaration) => void;
   TSNamedTupleMember?: (node: ESTree.TSNamedTupleMember) => void;
   'TSNamedTupleMember:exit'?: (node: ESTree.TSNamedTupleMember) => void;
   TSNamespaceExportDeclaration?: (node: ESTree.TSNamespaceExportDeclaration) => void;

crates/oxc_ast/src/ast/js.rs

@@ -1167,7 +1167,8 @@ pub enum Declaration<'a> {
     TSInterfaceDeclaration(Box<'a, TSInterfaceDeclaration<'a>>) = 36,
     TSEnumDeclaration(Box<'a, TSEnumDeclaration<'a>>) = 37,
     TSModuleDeclaration(Box<'a, TSModuleDeclaration<'a>>) = 38,
-    TSImportEqualsDeclaration(Box<'a, TSImportEqualsDeclaration<'a>>) = 39,
+    TSGlobalDeclaration(Box<'a, TSGlobalDeclaration<'a>>) = 39,
+    TSImportEqualsDeclaration(Box<'a, TSImportEqualsDeclaration<'a>>) = 40,
 }
 
 /// Macro for matching `Declaration`'s variants.
@@ -1181,6 +1182,7 @@ macro_rules! match_declaration {
             | $ty::TSInterfaceDeclaration(_)
             | $ty::TSEnumDeclaration(_)
             | $ty::TSModuleDeclaration(_)
+            | $ty::TSGlobalDeclaration(_)
             | $ty::TSImportEqualsDeclaration(_)
     };
 }

crates/oxc_ast/src/ast/macros.rs

@@ -448,7 +448,9 @@ macro_rules! inherit_variants {
                 /// Inherited from [`Declaration`]
                 TSModuleDeclaration(Box<'a, TSModuleDeclaration<'a>>) = 38,
                 /// Inherited from [`Declaration`]
-                TSImportEqualsDeclaration(Box<'a, TSImportEqualsDeclaration<'a>>) = 39,
+                TSGlobalDeclaration(Box<'a, TSGlobalDeclaration<'a>>) = 39,
+                /// Inherited from [`Declaration`]
+                TSImportEqualsDeclaration(Box<'a, TSImportEqualsDeclaration<'a>>) = 40,
 
                 $($rest)*
             }
@@ -471,6 +473,7 @@ macro_rules! inherit_variants {
                 TSInterfaceDeclaration,
                 TSEnumDeclaration,
                 TSModuleDeclaration,
+                TSGlobalDeclaration,
                 TSImportEqualsDeclaration,
             ]
         );

crates/oxc_ast/src/ast/ts.rs

@@ -1167,61 +1167,42 @@ pub enum TSTypePredicateName<'a> {
 ///
 /// ## Examples
 /// ```ts
-/// declare module 'foo' {
+/// declare module 'foo' { }
 /// // kind ^^^^^^ ^^^^^ id
-/// }
 /// ```
 ///
 /// ```ts
 /// namespace Foo { }
 /// declare namespace Bar { }
-/// ```
-///
-/// ```ts
-/// declare global {
-///     interface Window {
-///        customProp: string;
-///     }
-/// }
+/// // kind ^^^^^^^^^ ^^^ id
 /// ```
 ///
 /// ## References
 /// * [TypeScript Handbook - Namespaces](https://www.typescriptlang.org/docs/handbook/2/modules.html#namespaces)
 /// * [TypeScript Handbook - Module Augmentation](https://www.typescriptlang.org/docs/handbook/declaration-merging.html#module-augmentation)
-/// * [TypeScript Handbook - Global Augmentation](https://www.typescriptlang.org/docs/handbook/declaration-merging.html#global-augmentation)
 #[ast(visit)]
 #[scope(
     flags = ScopeFlags::TsModuleBlock,
     strict_if = self.body.as_ref().is_some_and(TSModuleDeclarationBody::has_use_strict_directive),
 )]
 #[derive(Debug)]
 #[generate_derive(CloneIn, Dummy, TakeIn, GetSpan, GetSpanMut, ContentEq, ESTree, UnstableAddress)]
-#[estree(
-    via = TSModuleDeclarationConverter,
-    add_fields(global = TSModuleDeclarationGlobal),
-)]
+#[estree(via = TSModuleDeclarationConverter, add_fields(global = False))]
 pub struct TSModuleDeclaration<'a> {
     pub span: Span,
     /// The name of the module/namespace being declared.
-    ///
-    /// Note that for `declare global {}`, no symbol will be created for the module name.
     #[estree(ts_type = "BindingIdentifier | StringLiteral | TSQualifiedName")]
     pub id: TSModuleDeclarationName<'a>,
     #[scope(enter_before)]
     #[estree(ts_type = "TSModuleBlock | null")]
     pub body: Option<TSModuleDeclarationBody<'a>>,
     /// The keyword used to define this module declaration.
     ///
-    /// Helps discriminate between global overrides vs module declarations vs namespace
-    /// declarations.
-    ///
     /// ```ts
     /// namespace Foo {}
     /// ^^^^^^^^^
     /// module 'foo' {}
     /// ^^^^^^
-    /// declare global {}
-    ///         ^^^^^^
     /// ```
     pub kind: TSModuleDeclarationKind,
     pub declare: bool,
@@ -1232,12 +1213,10 @@ pub struct TSModuleDeclaration<'a> {
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 #[generate_derive(CloneIn, Dummy, ContentEq, ESTree)]
 pub enum TSModuleDeclarationKind {
-    /// `declare global {}`
-    Global = 0,
-    /// `declare module 'foo' {}`
-    Module = 1,
+    /// `module Foo {}`, `declare module 'foo' {}`
+    Module = 0,
     /// `namespace Foo {}`
-    Namespace = 2,
+    Namespace = 1,
 }
 
 /// The name of a TypeScript [namespace or module declaration](TSModuleDeclaration).
@@ -1278,6 +1257,40 @@ pub enum TSModuleDeclarationBody<'a> {
     TSModuleBlock(Box<'a, TSModuleBlock<'a>>) = 1,
 }
 
+/// TypeScript Global Declaration
+///
+/// ## Examples
+/// ```ts
+/// declare global {
+///     interface Window {
+///        customProp: string;
+///     }
+/// }
+/// ```
+///
+/// ## References
+/// * [TypeScript Handbook - Global Augmentation](https://www.typescriptlang.org/docs/handbook/declaration-merging.html#global-augmentation)
+#[ast(visit)]
+// Directives are not allowed in `global {}` blocks, so no need for `strict_if` condition
+#[scope(flags = ScopeFlags::TsModuleBlock)]
+#[derive(Debug)]
+#[generate_derive(CloneIn, Dummy, TakeIn, GetSpan, GetSpanMut, ContentEq, ESTree, UnstableAddress)]
+#[estree(
+    rename = "TSModuleDeclaration",
+    add_fields(id = TSGlobalDeclarationId, kind = Global, global = True),
+    field_order(id, body, kind, declare, global, span),
+)]
+pub struct TSGlobalDeclaration<'a> {
+    pub span: Span,
+    /// Span of `global` keyword
+    #[estree(skip)]
+    pub global_span: Span,
+    pub body: TSModuleBlock<'a>,
+    pub declare: bool,
+    pub scope_id: Cell<Option<ScopeId>>,
+}
+
+/// Body block of a [`TSModuleDeclaration`] or [`TSGlobalDeclaration`].
 #[ast(visit)]
 #[derive(Debug)]
 #[generate_derive(CloneIn, Dummy, TakeIn, GetSpan, GetSpanMut, ContentEq, ESTree, UnstableAddress)]

crates/oxc_ast/src/ast_impl/js.rs

@@ -1113,6 +1113,7 @@ impl<'a> Declaration<'a> {
     /// const x = 1; // None. may change in the future.
     /// class Foo {} // Some(IdentifierReference { name: "Foo", .. })
     /// enum Bar {} // Some(IdentifierReference { name: "Bar", .. })
+    /// declare global {} // None
     /// ```
     pub fn id(&self) -> Option<&BindingIdentifier<'a>> {
         match self {
@@ -1129,7 +1130,7 @@ impl<'a> Declaration<'a> {
                     None
                 }
             }
-            Declaration::VariableDeclaration(_) => None,
+            Declaration::TSGlobalDeclaration(_) | Declaration::VariableDeclaration(_) => None,
         }
     }
 
@@ -1142,6 +1143,7 @@ impl<'a> Declaration<'a> {
             Declaration::TSEnumDeclaration(decl) => decl.declare,
             Declaration::TSTypeAliasDeclaration(decl) => decl.declare,
             Declaration::TSModuleDeclaration(decl) => decl.declare,
+            Declaration::TSGlobalDeclaration(decl) => decl.declare,
             Declaration::TSInterfaceDeclaration(decl) => decl.declare,
             Declaration::TSImportEqualsDeclaration(_) => false,
         }

crates/oxc_ast/src/ast_impl/ts.rs

@@ -186,16 +186,10 @@ impl TSModuleDeclaration<'_> {
 }
 
 impl TSModuleDeclarationKind {
-    /// Returns `true` for `declare global { ... }`
-    pub fn is_global(self) -> bool {
-        matches!(self, TSModuleDeclarationKind::Global)
-    }
-
     /// Declaration keyword as a string, identical to how it would appear in the
     /// source code.
     pub fn as_str(self) -> &'static str {
         match self {
-            Self::Global => "global",
             Self::Module => "module",
             Self::Namespace => "namespace",
         }

crates/oxc_ast/src/ast_kind_impl.rs

@@ -31,7 +31,7 @@ impl<'a> AstKind<'a> {
     pub fn is_declaration(self) -> bool {
         matches!(self, Self::Function(func) if func.is_declaration())
         || matches!(self, Self::Class(class) if class.is_declaration())
-        || matches!(self, Self::TSEnumDeclaration(_) | Self::TSModuleDeclaration(_)
+        || matches!(self, Self::TSEnumDeclaration(_) | Self::TSModuleDeclaration(_) | Self::TSGlobalDeclaration(_)
             | Self::VariableDeclaration(_) | Self::TSInterfaceDeclaration(_)
             | Self::TSTypeAliasDeclaration(_) | Self::TSImportEqualsDeclaration(_) | Self::PropertyDefinition(_)
         ) || self.is_module_declaration()
@@ -570,6 +570,7 @@ impl AstKind<'_> {
             Self::TSInterfaceDeclaration(_) => "TSInterfaceDeclaration".into(),
             Self::TSInterfaceHeritage(_) => "TSInterfaceHeritage".into(),
             Self::TSModuleDeclaration(m) => format!("TSModuleDeclaration({})", m.id).into(),
+            Self::TSGlobalDeclaration(_) => "TSGlobalDeclaration".into(),
             Self::TSTypeAliasDeclaration(_) => "TSTypeAliasDeclaration".into(),
             Self::TSTypeAnnotation(_) => "TSTypeAnnotation".into(),
             Self::TSTypeQuery(_) => "TSTypeQuery".into(),