Skip to content

Commit ce251ba

Browse files
feat: Port complete ESTree type definitions from typescript-estree to Go
## Summary This PR implements the complete type system for ESTree nodes in Go, porting all base ESTree node types and TypeScript-specific extensions (TSESTree types) from typescript-estree. ## Changes ### New Type Files - **positions.go** - Position, SourceLocation, Range types for source location tracking - **base.go** - Core Node interface, BaseNode implementation, and fundamental types - **expressions.go** - All expression node types (40+ types including ES5-ES2022) - **statements.go** - All statement and declaration types (30+ types) - **patterns.go** - Destructuring pattern types for ES2015+ - **typescript.go** - Complete TypeScript-specific node types (60+ types) - **tokens.go** - Token types, keywords, and punctuators - **README.md** - Comprehensive documentation for the type system ### Updated Files - **types_test.go** - Comprehensive unit tests covering: - Node interface implementation - JSON serialization/deserialization - All major node types (base, expressions, statements, patterns, TypeScript) - Token and comment types ### Removed Files - **types.go** - Replaced by the modular file structure ### Other Changes - **go.work** - Removed non-existent typescript-go reference ## Type Coverage ### Base ESTree (ES5-ES2022) ✅ All expression types (literals, operators, functions, classes, etc.) ✅ All statement types (control flow, loops, declarations, modules, etc.) ✅ All pattern types (destructuring for ES2015+) ✅ Position and location types ✅ Token and comment types ### TypeScript Extensions (TSESTree) ✅ All type annotation types (primitives, complex types, etc.) ✅ All TypeScript declarations (interface, type alias, enum, module) ✅ All TypeScript expressions (as, satisfies, non-null assertion) ✅ Type parameters and instantiation ✅ Advanced types (conditional, mapped, indexed access, etc.) ## Technical Implementation - All types implement the `Node` interface - Marker interfaces for categorization (Statement, Expression, Declaration, Pattern, TSType) - Go struct embedding for type hierarchies - JSON struct tags for ESTree-compliant serialization - Comprehensive documentation comments for each type - Zero external dependencies ## Testing All tests pass: ``` go test ./types/... ok github.com/web-infra-dev/rslint/internal/typescript-estree/types 0.003s ``` ## References - ESTree specification: https://github.com/estree/estree - TypeScript-ESTree: https://github.com/typescript-eslint/typescript-eslint/tree/main/packages/typescript-estree - TypeScript-ESTree AST spec: https://typescript-eslint.io/packages/typescript-estree/ast-spec/ ## Related Follow-up to #3 (TypeScript ESTree infrastructure setup) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
1 parent a43c2b9 commit ce251ba

File tree

11 files changed

+2162
-71
lines changed

11 files changed

+2162
-71
lines changed

go.work

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,5 +5,4 @@ toolchain go1.25.0
55
use (
66
.
77
./internal/typescript-estree
8-
./typescript-go
98
)
Lines changed: 280 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,280 @@
1+
# ESTree Type Definitions for TypeScript
2+
3+
This package provides comprehensive Go type definitions for ESTree-compliant Abstract Syntax Trees (ASTs), including full support for TypeScript-specific extensions (TSESTree).
4+
5+
## Overview
6+
7+
The types in this package represent the complete ESTree specification from ES5 through ES2022+, plus all TypeScript-specific node types. These types are used to represent JavaScript and TypeScript code as structured data that can be analyzed, transformed, and manipulated programmatically.
8+
9+
## Package Structure
10+
11+
The types are organized into logical files:
12+
13+
- **`positions.go`** - Source location types (Position, SourceLocation, Range)
14+
- **`base.go`** - Core node interfaces and base types (Node, Statement, Expression, etc.)
15+
- **`expressions.go`** - All expression node types (BinaryExpression, CallExpression, etc.)
16+
- **`statements.go`** - All statement and declaration types (IfStatement, FunctionDeclaration, etc.)
17+
- **`patterns.go`** - Destructuring pattern types (ArrayPattern, ObjectPattern, etc.)
18+
- **`typescript.go`** - TypeScript-specific node types (TSInterfaceDeclaration, TSTypeAnnotation, etc.)
19+
- **`tokens.go`** - Token and comment type definitions
20+
21+
## Core Interfaces
22+
23+
### Node
24+
25+
All AST nodes implement the `Node` interface:
26+
27+
```go
28+
type Node interface {
29+
Type() string // Returns the node type (e.g., "Identifier")
30+
Loc() *SourceLocation // Returns source location information
31+
GetRange() Range // Returns character range [start, end]
32+
}
33+
```
34+
35+
### Marker Interfaces
36+
37+
The package defines several marker interfaces to categorize nodes:
38+
39+
- **`Statement`** - All statement nodes
40+
- **`Expression`** - All expression nodes
41+
- **`Declaration`** - All declaration nodes (subset of statements)
42+
- **`Pattern`** - All pattern nodes (used in destructuring)
43+
- **`ModuleDeclaration`** - All module-level declarations
44+
- **`TSType`** - All TypeScript type nodes
45+
46+
## Base Types
47+
48+
### BaseNode
49+
50+
All concrete node types embed `BaseNode`, which provides the standard implementation of the `Node` interface:
51+
52+
```go
53+
type BaseNode struct {
54+
NodeType string `json:"type"`
55+
Location *SourceLocation `json:"loc,omitempty"`
56+
Span Range `json:"range,omitempty"`
57+
}
58+
```
59+
60+
### Position and Location
61+
62+
```go
63+
type Position struct {
64+
Line int `json:"line"` // 1-indexed line number
65+
Column int `json:"column"` // 0-indexed column number
66+
}
67+
68+
type SourceLocation struct {
69+
Start Position `json:"start"`
70+
End Position `json:"end"`
71+
}
72+
73+
type Range [2]int // Character offsets: [start, end]
74+
```
75+
76+
## Expression Types
77+
78+
The package includes all ESTree expression types:
79+
80+
- **Literals**: `SimpleLiteral`, `RegExpLiteral`, `BigIntLiteral`
81+
- **Identifiers**: `Identifier`, `PrivateIdentifier`
82+
- **Operators**: `UnaryExpression`, `BinaryExpression`, `LogicalExpression`, `UpdateExpression`
83+
- **Functions**: `FunctionExpression`, `ArrowFunctionExpression`
84+
- **Objects**: `ObjectExpression`, `ArrayExpression`
85+
- **Member Access**: `MemberExpression`, `CallExpression`, `NewExpression`
86+
- **Conditionals**: `ConditionalExpression`
87+
- **Templates**: `TemplateLiteral`, `TaggedTemplateExpression`
88+
- **Classes**: `ClassExpression`
89+
- **Modern Features**: `AwaitExpression`, `YieldExpression`, `ChainExpression`, `ImportExpression`
90+
91+
## Statement Types
92+
93+
All statement types are included:
94+
95+
- **Control Flow**: `IfStatement`, `SwitchStatement`, `SwitchCase`
96+
- **Loops**: `ForStatement`, `ForInStatement`, `ForOfStatement`, `WhileStatement`, `DoWhileStatement`
97+
- **Blocks**: `BlockStatement`, `EmptyStatement`
98+
- **Declarations**: `VariableDeclaration`, `FunctionDeclaration`, `ClassDeclaration`
99+
- **Exception Handling**: `TryStatement`, `CatchClause`, `ThrowStatement`
100+
- **Flow Control**: `ReturnStatement`, `BreakStatement`, `ContinueStatement`
101+
- **Modules**: `ImportDeclaration`, `ExportNamedDeclaration`, `ExportDefaultDeclaration`, `ExportAllDeclaration`
102+
- **Other**: `ExpressionStatement`, `LabeledStatement`, `WithStatement`, `DebuggerStatement`
103+
104+
## Pattern Types
105+
106+
Destructuring patterns for ES2015+:
107+
108+
- `ArrayPattern` - Array destructuring `[a, b, c]`
109+
- `ObjectPattern` - Object destructuring `{x, y, z}`
110+
- `AssignmentPattern` - Default values `{x = 10}`
111+
- `RestElement` - Rest patterns `{...rest}`
112+
- `AssignmentProperty` - Object pattern properties
113+
114+
## TypeScript Types
115+
116+
### Type Annotations
117+
118+
- `TSTypeAnnotation` - Wraps a type annotation
119+
- `TSType` - Interface for all TypeScript type nodes
120+
121+
### Primitive Type Keywords
122+
123+
All TypeScript primitive types:
124+
125+
```
126+
TSAnyKeyword, TSUnknownKeyword, TSNumberKeyword, TSBooleanKeyword,
127+
TSStringKeyword, TSSymbolKeyword, TSVoidKeyword, TSNullKeyword,
128+
TSUndefinedKeyword, TSNeverKeyword, TSBigIntKeyword, TSObjectKeyword
129+
```
130+
131+
### Complex Types
132+
133+
- **Union/Intersection**: `TSUnionType`, `TSIntersectionType`
134+
- **Arrays/Tuples**: `TSArrayType`, `TSTupleType`
135+
- **Functions**: `TSFunctionType`, `TSConstructorType`
136+
- **Literals**: `TSLiteralType`, `TSTemplateLiteralType`
137+
- **References**: `TSTypeReference`, `TSQualifiedName`
138+
- **Advanced**: `TSConditionalType`, `TSInferType`, `TSMappedType`, `TSIndexedAccessType`
139+
- **Queries**: `TSTypeQuery`, `TSImportType`
140+
- **Modifiers**: `TSOptionalType`, `TSRestType`
141+
142+
### Declarations
143+
144+
- `TSInterfaceDeclaration` - Interface declarations
145+
- `TSTypeAliasDeclaration` - Type alias declarations
146+
- `TSEnumDeclaration` - Enum declarations
147+
- `TSModuleDeclaration` - Namespace/module declarations
148+
149+
### Expressions
150+
151+
- `TSAsExpression` - Type assertions with `as`
152+
- `TSTypeAssertion` - Type assertions with `<Type>`
153+
- `TSNonNullExpression` - Non-null assertions `expr!`
154+
- `TSSatisfiesExpression` - Satisfies expressions (TypeScript 4.9+)
155+
- `TSInstantiationExpression` - Type instantiation `expr<T>`
156+
157+
## Token Types
158+
159+
The package defines token types for lexical analysis:
160+
161+
```go
162+
type TokenType string
163+
164+
const (
165+
TokenBoolean TokenType = "Boolean"
166+
TokenNull TokenType = "Null"
167+
TokenNumeric TokenType = "Numeric"
168+
TokenString TokenType = "String"
169+
TokenIdentifier TokenType = "Identifier"
170+
TokenKeyword TokenType = "Keyword"
171+
TokenPunctuator TokenType = "Punctuator"
172+
// ... and more
173+
)
174+
```
175+
176+
All JavaScript and TypeScript keywords are defined as constants, along with all punctuators.
177+
178+
## JSON Serialization
179+
180+
All types include `json` struct tags for seamless serialization/deserialization:
181+
182+
```go
183+
program := &types.Program{
184+
BaseNode: types.BaseNode{
185+
NodeType: "Program",
186+
Location: &types.SourceLocation{
187+
Start: types.Position{Line: 1, Column: 0},
188+
End: types.Position{Line: 1, Column: 10},
189+
},
190+
Span: types.Range{0, 10},
191+
},
192+
SourceType: "module",
193+
Body: []types.Statement{},
194+
}
195+
196+
data, err := json.Marshal(program)
197+
// Produces ESTree-compliant JSON
198+
```
199+
200+
## Usage Examples
201+
202+
### Creating an AST Node
203+
204+
```go
205+
// Create an identifier
206+
id := &types.Identifier{
207+
BaseNode: types.BaseNode{
208+
NodeType: "Identifier",
209+
Location: &types.SourceLocation{
210+
Start: types.Position{Line: 1, Column: 0},
211+
End: types.Position{Line: 1, Column: 3},
212+
},
213+
Span: types.Range{0, 3},
214+
},
215+
Name: "foo",
216+
}
217+
218+
// Create a variable declaration
219+
varDecl := &types.VariableDeclaration{
220+
BaseNode: types.BaseNode{NodeType: "VariableDeclaration"},
221+
Declarations: []types.VariableDeclarator{
222+
{
223+
BaseNode: types.BaseNode{NodeType: "VariableDeclarator"},
224+
ID: id,
225+
},
226+
},
227+
Kind: "const",
228+
}
229+
```
230+
231+
### TypeScript Type Annotations
232+
233+
```go
234+
// Create a TypeScript interface
235+
iface := &types.TSInterfaceDeclaration{
236+
BaseNode: types.BaseNode{NodeType: "TSInterfaceDeclaration"},
237+
ID: &types.Identifier{
238+
BaseNode: types.BaseNode{NodeType: "Identifier"},
239+
Name: "MyInterface",
240+
},
241+
Body: &types.TSInterfaceBody{
242+
BaseNode: types.BaseNode{NodeType: "TSInterfaceBody"},
243+
Body: []types.Node{},
244+
},
245+
Extends: []types.TSInterfaceHeritage{},
246+
}
247+
```
248+
249+
## References
250+
251+
- [ESTree Specification](https://github.com/estree/estree)
252+
- [TypeScript-ESTree](https://github.com/typescript-eslint/typescript-eslint/tree/main/packages/typescript-estree)
253+
- [TypeScript-ESTree AST Spec](https://typescript-eslint.io/packages/typescript-estree/ast-spec/)
254+
- [@types/estree](https://www.npmjs.com/package/@types/estree)
255+
256+
## Testing
257+
258+
The package includes comprehensive unit tests covering:
259+
260+
- Node interface implementation
261+
- JSON serialization/deserialization
262+
- Type correctness
263+
- All major node types
264+
265+
Run tests with:
266+
267+
```bash
268+
go test ./types/...
269+
```
270+
271+
## Contributing
272+
273+
When adding new node types:
274+
275+
1. Place them in the appropriate file based on their category
276+
2. Ensure they embed `BaseNode`
277+
3. Implement the appropriate marker interface(s)
278+
4. Add `json` struct tags for all fields
279+
5. Add comprehensive documentation comments
280+
6. Include unit tests

0 commit comments

Comments
 (0)