feat: Set up TypeScript ESTree infrastructure

[delino]

Summary

This PR sets up the foundational infrastructure and build configuration necessary for the TypeScript ESTree port into rslint. This contains only scaffolding and infrastructure - no actual parser implementation.

What's Included

• ✅ Module Structure: New Go module at internal/typescript-estree/ with organized packages
• ✅ Build Configuration: Makefile targets, go.mod, and workspace updates
• ✅ Type Definitions: ESTree-compliant base types and interfaces
• ✅ Test Infrastructure: Working tests with parallel execution support
• ✅ CI/CD Integration: Automatic inclusion in existing CI workflows
• ✅ Documentation: Comprehensive README and setup guide

Directory Structure

internal/typescript-estree/
├── parser/          # Parsing logic (placeholder)
├── converter/       # AST conversion (placeholder)
├── types/           # ESTree type definitions
├── utils/           # Utility functions
├── testutils/       # Testing utilities
├── go.mod           # Module dependencies
└── README.md        # Documentation

Verification

All infrastructure is verified to work:

# Tests pass
$ go test ./internal/typescript-estree/...
ok      github.com/web-infra-dev/rslint/internal/typescript-estree/converter (cached)
ok      github.com/web-infra-dev/rslint/internal/typescript-estree/parser    (cached)
ok      github.com/web-infra-dev/rslint/internal/typescript-estree/types     (cached)
ok      github.com/web-infra-dev/rslint/internal/typescript-estree/utils     (cached)

# Module dependencies resolve
$ cd internal/typescript-estree && go mod tidy
# No errors

New Makefile Targets

make test-typescript-estree              # Run tests
make test-coverage-typescript-estree     # Run with coverage
make lint-typescript-estree              # Run linters

What's NOT Included

• ❌ Parser implementation (pending)
• ❌ Converter implementation (pending)
• ❌ Comprehensive test coverage (pending)
• ❌ JSX support (pending)

This infrastructure must be merged first before any feature implementation work can begin.

Test plan

• All tests pass: go test ./internal/typescript-estree/...
• Module builds successfully
• Dependencies resolve correctly
• Linting configuration works
• Documentation is complete

Related Issues

Part of the TypeScript ESTree porting effort for rslint.

References

• TypeScript ESTree
• ESTree Specification
• TypeScript-Go
• Setup Documentation

🤖 Generated with Claude Code

[kdy1]

🤖 This pull request has been linked to AutoDev Task #778

View the task details and manage the automated development workflow in AutoDev.

[kdy1]

📋 AutoDev Task Prompt

Objective

Set up the CI/CD infrastructure and build configuration necessary for the typescript-estree port into rslint.
This task must be completed FIRST before any feature work begins.

Documentation & Resources

• Go modules documentation: https://go.dev/doc/modules/managing-dependencies
• Go testing best practices: https://go.dev/doc/tutorial/add-a-test
• GitHub Actions for Go: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-go
• TypeScript-Go project structure: https://github.com/microsoft/typescript-go
• Rslint architecture: https://github.com/web-infra-dev/rslint/blob/main/architecture.md

Scope

This task focuses on setting up the infrastructure without implementing features:

• Create new Go module structure for typescript-estree port under internal/typescript-estree/
• Set up Go module dependencies and version management
• Configure CI pipeline to build and test the new module
• Add linting configuration (golangci-lint) for the new module
• Create initial directory structure matching typescript-estree organization
• Set up test infrastructure and test runner configuration
• Add build scripts and Makefile targets for the new module
• Configure code coverage reporting

Technical Requirements

• Follow existing rslint Go module structure in internal/ directory
• Use Go 1.21+ for modern language features
• Integrate with existing CI workflows in .github/workflows/
• Follow the existing golangci-lint configuration in .golangci.yml
• Create directory structure:

  internal/typescript-estree/
  ├── parser/          # Main parsing logic
  ├── converter/       # AST conversion logic
  ├── types/           # Type definitions for ESTree nodes
  ├── utils/           # Utility functions
  ├── testutils/       # Testing utilities
  └── ...
  

Out of Scope

• DO NOT implement any parser functionality
• DO NOT port any typescript-estree code yet
• Focus only on infrastructure and scaffolding

Success Criteria

• CI pipeline successfully builds the new module
• Test infrastructure is in place and can run (even with empty tests)
• Linting passes for scaffolding code
• Documentation on how to build and test the module is created
• Directory structure is created and follows Go best practices

Reference Implementation

• Similar structure: https://github.com/typescript-eslint/typescript-eslint/tree/main/packages/typescript-estree

---

This comment was automatically added by AutoDev. You can disable this feature in AutoDev Settings.

[claude]

Code Review: TypeScript ESTree Infrastructure Setup

Summary

This PR establishes foundational infrastructure for porting @typescript-eslint/typescript-estree to Go. The code quality is excellent, with well-organized structure, proper documentation, and good testing foundations. This is a solid scaffolding PR that sets up the project for future implementation work.

✅ Code Quality and Best Practices

Strengths

1. Excellent Module Organization: The package structure (parser/, converter/, types/, utils/, testutils/) closely mirrors the TypeScript ESTree architecture, making the port more maintainable.

2. Proper Go Idioms: Code follows Go best practices:

   • Exported types and functions have documentation comments
   • Interfaces are properly defined (Node interface in types/types.go:9-17)
   • Use of embedding with BaseNode is idiomatic
   • Test files use t.Parallel() for concurrent execution

3. Build Infrastructure: Well-crafted Makefile with clear targets and help documentation (Makefile:1-50)

4. Documentation: Comprehensive documentation at multiple levels:

   • Module README (internal/typescript-estree/README.md)
   • Setup guide (TYPESCRIPT_ESTREE_SETUP.md)
   • Inline code documentation

Minor Suggestions

1. Typo in LICENSE Path: In internal/typescript-estree/README.md:190, the license link references ../../LICENSE but should verify this path is correct from the module directory.

2. CONTRIBUTING.md Reference: internal/typescript-estree/README.md:161 references ../../CONTRIBUTING.md - confirmed this file exists, so this is correct.

3. Module Import Paths: The module uses github.com/web-infra-dev/rslint but the repository is kdy1/rslint. Ensure this is intentional for when the code is merged upstream.

🐛 Potential Bugs and Issues

Critical Issues: None Found

Minor Issues

1. JSON Tag Inconsistency: In types/types.go:36, BaseNode.Span uses tag json:"range,omitempty" but the field is an array [2]int. Empty arrays won't be omitted with omitempty - the array will always be marshaled. Consider if this is the desired behavior.

2. Nil Handling in Converter: converter/converter.go:44-51 returns nil, nil which could cause nil pointer dereferences if callers don't check the error. Consider returning a sentinel error like:

   return nil, fmt.Errorf("conversion not implemented")

3. Parser Returns: parser/parser.go:29-36 similarly returns nil, nil. Same suggestion applies.

4. Default Options Pattern: In converter/converter.go:32-35, the constructor handles nil options gracefully. Consider doing the same for parser.Parse() if options are optional.

⚡ Performance Considerations

Positive Aspects

1. Parallel Testing: All tests use t.Parallel(), which will improve test suite performance as more tests are added.

2. Efficient Data Structures: Use of arrays for ranges ([2]int) is more efficient than slices for fixed-size data.

Suggestions

1. Future Consideration - String Interning: When implementing the parser, consider string interning for common identifiers like "type", "name", etc. to reduce memory allocations.

2. Preallocate Slices: When implementing Program.Body population in the parser, preallocate slices with estimated capacity to reduce allocations:

   body := make([]Node, 0, estimatedSize)

🔒 Security Concerns

Assessment: No Security Issues Found

This infrastructure PR contains no security vulnerabilities. The code:

• Has no user input handling yet
• No file system operations outside of tests
• No network operations
• No cryptographic operations
• Proper use of the depguard linter rule to prevent unsafe JSON library usage (.golangci.yml:65-70)

Future Recommendations

When implementing the parser:

1. Add input size limits to prevent DoS attacks via extremely large source files
2. Implement timeout mechanisms for parsing operations
3. Validate source location bounds to prevent out-of-bounds access
4. Consider memory limits for deeply nested AST structures

🧪 Test Coverage

Current State

Test Infrastructure: ✅ Excellent foundation

• All packages have test files
• Tests use table-driven patterns (utils/utils_test.go:26-45)
• Test utilities package provides good helpers
• Tests are skipped appropriately for unimplemented functionality

Coverage Gaps (Expected for Infrastructure PR)

As noted in the PR description, these are expected and will be addressed in future PRs:

• Parser implementation tests (currently skipped: parser/parser_test.go:35)
• Converter implementation tests (currently skipped: converter/converter_test.go:33)
• Integration tests for end-to-end parsing

Recommendations

1. Coverage Tracking: The Makefile includes coverage targets - ensure these are run in CI. I verified CI configuration (.github/workflows/ci.yml:57) runs Go tests, which will include this module.

2. Benchmark Tests: Consider adding benchmark tests for parser performance comparisons as implementation progresses:

   func BenchmarkParse(b *testing.B) {
       for i := 0; i < b.N; i++ {
           Parse(testSource, nil)
       }
   }

3. Fuzz Testing: Once the parser is implemented, add fuzz tests to discover edge cases:

   func FuzzParse(f *testing.F) {
       f.Fuzz(func(t *testing.T, source string) {
           Parse(source, nil)
       })
   }

📋 Additional Observations

Positive Points

1. CI Integration: The module will automatically be included in existing CI workflows (go test ./internal/...) without additional configuration.

2. Workspace Configuration: Proper use of Go workspaces (go.work:7) for multi-module development.

3. Module Dependencies: Appropriate use of replace directives (internal/typescript-estree/go.mod:14-17) for local development with the typescript-go shim.

4. Linter Configuration: The existing .golangci.yml is comprehensive and will catch common issues.

Questions/Clarifications

1. Module Versioning: go.mod uses v0.0.0 for the shim packages - is this intentional for development, or should these reference specific versions?

2. Error Handling Strategy: What error handling strategy will be used? Consider defining common error types in a separate errors.go file:

   var (
       ErrInvalidSourceType = errors.New("invalid source type")
       ErrParsingFailed     = errors.New("parsing failed")
   )

🎯 Verdict

Recommendation: ✅ APPROVE

This is an exemplary infrastructure PR. The code is:

• Well-structured and follows Go best practices
• Properly documented
• Ready for future implementation work
• Has no blocking issues

The infrastructure provides a solid foundation for the TypeScript ESTree port. The minor suggestions above are non-blocking and can be addressed in follow-up PRs during implementation.

Next Steps

As noted in the PR description, the next phases should focus on:

1. Porting core parser functionality from TypeScript ESTree
2. Implementing the AST converter
3. Adding comprehensive test coverage with real-world test cases
4. Supporting JSX parsing

Great work on this foundational setup! 🚀

---

Generated with Claude Code - Code Review