feat: Add oxc-inspired transformer infrastructure

[delino]

Summary

This PR introduces the foundational infrastructure for an oxc-inspired transformer implementation built on SWC's visitor patterns. The design adapts oxc's composable architecture to work with SWC's VisitMut and VisitMutHook traits.

Key Components

• New swc_ecma_transformer crate: Provides composable transformation infrastructure
• TraverseCtx: Context type for passing state and utilities through transformation hooks
• Transformation options: Comprehensive configuration for TypeScript, JSX, ES targets, decorators, and RegExp
• Module structure: Organized to mirror oxc's architecture with ES20XX, feature, and infrastructure modules
• Main Transformer struct: Implements VisitMut and orchestrates hook-based transformations

Architecture

The implementation adapts oxc's design to SWC's patterns:

Aspect	oxc	SWC Implementation
Visitor pattern	Single Traverse trait	VisitMut + VisitMutHook<TraverseCtx>
AST allocation	Arena-based (&'a Allocator)	Heap-based (Box<T>)
Scope management	Explicit scope tree	SyntaxContext with marks
Hook composition	Layered trait impl	CompositeHook pattern

Module Organization

swc_ecma_transformer/
├── src/
│   ├── lib.rs           # Main Transformer struct
│   ├── context.rs       # TraverseCtx implementation
│   ├── options.rs       # Configuration types
│   ├── es2015/          # ES2015 transforms (placeholder)
│   ├── es2016/          # ES2016 transforms (placeholder)
│   ├── ... (es2017-es2026)
│   ├── jsx/             # JSX transforms (placeholder)
│   ├── typescript/      # TypeScript transforms (placeholder)
│   ├── decorator/       # Decorator transforms (placeholder)
│   ├── regexp/          # RegExp transforms (placeholder)
│   ├── common/          # Shared utilities (placeholder)
│   ├── proposals/       # Experimental proposals (placeholder)
│   └── utils/           # General utilities (placeholder)
└── ARCHITECTURE.md      # Comprehensive design documentation

Design Highlights

1. TraverseCtx: Provides utilities similar to oxc's context:

   • Syntax context management (unresolved_ctxt, top_level_ctxt)
   • Unique identifier generation (generate_uid_name)
   • AST building helpers (create_ident_expr, create_member_expr, etc.)
   • Optional user-defined state storage

2. Hook Composition: Individual transforms implement VisitMutHook<TraverseCtx> and can be composed using CompositeHook to create transformation pipelines

3. Layered Transforms: Planned execution order matches oxc:

   • Layer x0: TypeScript (type stripping)
   • Layer x1: JSX, Decorators
   • Layers x2-x4: ES20XX (reverse chronological: ES2022 → ES2015)
   • Layer x4: RegExp, Common utilities

4. Performance-First: Follows SWC conventions:

   • Uses &str for Atom creation
   • Minimizes allocations
   • Avoids unnecessary cloning

Current Status

✅ Infrastructure complete and compiles with cargo check
✅ Comprehensive documentation in ARCHITECTURE.md
⚠️ No actual transforms implemented yet (all modules are placeholders)

Next Steps

Future PRs will implement actual transforms by porting from oxc:

Phase 2: Core ES2015 transforms (arrow functions, classes, template literals, etc.)
Phase 3: Additional ES versions (ES2016-ES2022)
Phase 4: Feature transforms (JSX, TypeScript, Decorators, RegExp)
Phase 5: Performance optimization and comprehensive testing

Testing

Currently includes basic unit tests for:

• Transformer creation with default options
• Transformer with explicit marks
• TraverseCtx context creation

Comprehensive fixture tests will be added as transforms are implemented.

References

• oxc transformer source
• oxc Traverse trait
• SWC VisitMut API
• SWC hooks crate
• oxc transformer announcement

Related Issues

This PR addresses the infrastructure setup for porting oxc's transformer architecture to SWC, enabling future implementation of composable, performant transformations.

🤖 Generated with Claude Code

[changeset-bot]

⚠️ No Changeset found

Latest commit: a5c99c3

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[kdy1]

🤖 This pull request has been linked to DevBird Task #1680

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

Learn more about DevBird here or the announcement blog post here.

[kdy1]

📋 DevBird Task Prompt

Objective

Research and document the oxc transformer architecture to understand what needs to be ported to SWC. Set up the initial infrastructure for the new transformer implementation in swc_ecma_transforms.

Documentation & Resources

• oxc GitHub Repository: https://github.com/oxc-project/oxc
• oxc Transformer Source: https://github.com/oxc-project/oxc/tree/main/crates/oxc_transformer/src
• oxc Traverse Context: https://github.com/oxc-project/oxc/tree/main/crates/oxc_traverse/src
• oxc Transformer Alpha Announcement: https://oxc.rs/blog/2024-09-29-transformer-alpha
• oxc Transformer Documentation: https://oxc.rs/docs/guide/usage/transformer.html
• SWC VisitMut API: https://rustdoc.swc.rs/swc_ecma_visit/trait.VisitMut.html
• SWC Plugin Documentation: https://swc.rs/docs/plugin/ecmascript/getting-started
• SWC Plugin Cheatsheet: https://swc.rs/docs/plugin/ecmascript/cheatsheet

Scope

1. Research oxc Architecture:

   • Examine the oxc_transformer crate structure at https://github.com/oxc-project/oxc/tree/main/crates/oxc_transformer/src
   • Identify all ES20XX modules (es2015, es2016, es2017, es2018, es2019, es2020, es2021, es2022, es2026)
   • Document feature modules (jsx, typescript, decorator, regexp)
   • Understand infrastructure modules (common, options, plugins, proposals, utils)
   • Study TraverseCtx implementation and how it provides scope/ancestry/AST building utilities

2. Analyze Existing SWC Infrastructure:

   • Review swc_ecma_hooks crate to understand VisitMutHook trait pattern
   • Understand how SWC's VisitMut trait works vs oxc's Traverse trait
   • Examine existing transform implementations in swc_ecma_transforms_* crates

3. Create Initial Structure:

   • Create a new crate swc_ecma_transformer in the crates/ directory
   • Set up Cargo.toml with appropriate dependencies on:
     • swc_ecma_ast
     • swc_ecma_visit
     • swc_ecma_hooks
     • swc_common
   • Create initial lib.rs with module structure mirroring oxc organization
   • Create a TraverseCtx equivalent for SWC that implements context passing for VisitMutHook

4. Document Architecture Plan:

   • Create ARCHITECTURE.md documenting:
     • How oxc's Traverse trait maps to SWC's VisitMut + VisitMutHook pattern
     • How TraverseCtx functionality will be implemented in SWC context
     • Directory structure for ES20XX and feature modules
     • Transformer composition pattern (how main Transformer struct orchestrates hooks)

Technical Requirements

• Follow SWC project structure conventions as seen in existing crates
• The main Transformer struct MUST implement VisitMut
• Individual ES20XX and feature transforms MUST implement VisitMutHook
• DO NOT use nightly-only Rust features
• Follow the guidance in /home/runner/work/swc/swc/CLAUDE.md:
  • Write performant code
  • Use Cow or &str for Atom instances
  • Write comments and documentation in English
  • Prefer &str over Cow for Atom creation

Out of Scope

• Do not implement actual transform logic yet
• Do not modify other crates besides creating the new swc_ecma_transformer
• Do not port specific ES20XX transforms yet

Success Criteria

• New swc_ecma_transformer crate exists with proper Cargo.toml
• ARCHITECTURE.md documents the porting strategy
• Basic module structure matches oxc organization
• TraverseCtx or equivalent context type is defined
• Main Transformer struct skeleton implements VisitMut
• Example hook struct shows VisitMutHook pattern
• cargo check --all passes for the new crate
• Code follows project conventions from CLAUDE.md

---

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

[claude]

Pull Request Review: oxc-inspired Transformer Infrastructure

Summary

This PR introduces foundational infrastructure for an oxc-inspired transformer built on SWC's visitor patterns. While the architecture and design are well thought out, there is a critical compilation error that needs to be fixed before this can be merged.

---

Critical Issues

1. Duplicate EsVersion Enum - MUST FIX ❌

Location: crates/swc_ecma_transformer/src/options.rs:98-129

Problem: The crate defines its own EsVersion enum, but swc_ecma_ast already has an EsVersion enum. This causes:

• Compilation failure in tests (lib.rs:244)
• Ambiguous glob imports warning
• Type mismatch errors

Evidence:

error[E0308]: mismatched types
   --> crates/swc_ecma_transformer/src/lib.rs:244:50
    |
244 |         assert_eq!(transformer.options().target, EsVersion::EsNext);
    |                                                  ^^^^^^^^^^^^^^^^^ expected `options::EsVersion`, found `swc_ecma_ast::EsVersion`

Solution: Remove the custom EsVersion enum from options.rs and use swc_ecma_ast::EsVersion instead. Update TransformOptions to use:

use swc_ecma_ast::EsVersion;

pub struct TransformOptions {
    // ...
    pub target: EsVersion,
    // ...
}

This follows SWC's convention of using the canonical EsVersion from swc_ecma_ast.

---

Code Quality Issues

2. Unused Dependencies

Location: crates/swc_ecma_transformer/Cargo.toml:15-18

Several dependencies are declared but not currently used in any code:

• rustc-hash - Not used anywhere
• tracing - Not used (though likely needed for future transforms)
• swc_ecma_codegen (dev) - Only needed when you start testing output
• swc_ecma_parser (dev) - Only needed when you start testing

Recommendation: Either:

• Remove unused dependencies until needed, OR
• Add a TODO comment explaining they're for future use

This aligns with Rust best practices of keeping dependencies minimal.

3. Missing ES2023-ES2025 Modules

Location: Module structure in src/

The code defines EsVersion enum values for ES2023, ES2024, ES2025 (in options.rs), but doesn't create corresponding module files. The structure jumps from es2022 to es2026.

Impact: Inconsistency between options and module organization.

Recommendation: Either add the missing module files or remove those enum variants until implemented.

---

Design & Architecture

4. Well-Structured Design ✅

The architecture is well-designed and properly documented:

• Clean separation of concerns (context, options, transformer)
• Good use of SWC's two-trait pattern (VisitMut + VisitMutHook)
• Comprehensive ARCHITECTURE.md explaining design decisions
• Proper comparison with oxc's approach

5. Context Design Concern ⚠️

Location: crates/swc_ecma_transformer/src/context.rs:41

The state field uses Option<&'a mut dyn std::any::Any>:

state: Option<&'a mut dyn std::any::Any>,

Concerns:

• dyn Any can lead to runtime panics if downcasting fails
• Lifetime 'a requires careful management and may complicate usage
• Not clear from docs when/how this should be used

Recommendation:

• Add more documentation about safe usage patterns
• Consider using a type parameter instead: TraverseCtx<'a, S = ()> with a default unit type
• Add examples showing proper downcasting with error handling

6. Incomplete Hook Composition ⚠️

Location: crates/swc_ecma_transformer/src/lib.rs:207-234

The visit_mut_program method creates a context but doesn't use it:

fn visit_mut_program(&mut self, program: &mut Program) {
    let _ctx = self.create_context();  // Created but unused!
    // TODO: Build and compose the actual hook chain
    program.visit_mut_children_with(self);
}

Impact: The transformer currently does nothing. While acknowledged as infrastructure-only, this creates a disconnect between the documented design and actual implementation.

Recommendation: Add at least one simple no-op hook to demonstrate the composition pattern actually works, or move this to a TODO implementation in a separate branch.

---

Performance Considerations

7. Atom Usage ✅

Good adherence to performance guidelines:

• Uses sym: "foo".into() for Atom creation (context.rs:109, 144)
• Follows CLAUDE.md guideline: "prefer &str for Atom creation"

8. Allocation Concerns ⚠️

Location: crates/swc_ecma_transformer/src/context.rs:90-92

pub fn generate_uid_name(&mut self, base: &str) -> String {
    self.uid_counter += 1;
    format!("{}_{}", base, self.uid_counter)
}

Issue: Returns String instead of using SWC's atom system or more efficient string handling.

Impact: Allocates a new String each time. For heavy transformations, this could add up.

Recommendation: Consider returning Atom or Cow<'static, str> for better performance. Since these are temporary identifiers, interning them might be beneficial.

---

Testing

9. Minimal Test Coverage ⚠️

Location: crates/swc_ecma_transformer/src/lib.rs:237-267

Only 3 basic unit tests:

• Creation test
• Marks test
• Context creation test

Missing:

• Integration tests showing hook composition
• Tests for TraverseCtx helper methods
• Tests for unique ID generation
• Tests verifying the two-trait pattern works correctly

Recommendation: Add tests for:

#[test]
fn test_generate_uid_name() {
    let mut ctx = TraverseCtx::default();
    assert_eq!(ctx.generate_uid_name("temp"), "temp_1");
    assert_eq!(ctx.generate_uid_name("temp"), "temp_2");
}

#[test]
fn test_create_ident_expr() {
    let ctx = TraverseCtx::default();
    let expr = ctx.create_ident_expr("foo", DUMMY_SP);
    // Assert structure
}

From CLAUDE.md: "Write unit tests for your code."

---

Documentation

10. Excellent Documentation ✅

• Comprehensive ARCHITECTURE.md (327 lines)
• Well-documented modules and types
• Good use of doc comments with examples
• Clear comparison with oxc's approach

11. Missing Safety/Usage Warnings ⚠️

Location: crates/swc_ecma_transformer/src/context.rs:168-194

The state management methods (set_state, state, state_mut) lack warnings about:

• Thread safety (is this safe to use across threads?)
• When it's safe to downcast
• What happens if you downcast to the wrong type

Recommendation: Add # Safety or # Panics sections to these docs.

---

Security Concerns

12. No Major Security Issues ✅

• No unsafe code
• No obvious injection vectors
• Proper use of SWC's hygiene system (marks and syntax contexts)

---

Recommendations Summary

Must Fix Before Merge:

1. ❌ Fix EsVersion duplicate - Remove custom enum, use swc_ecma_ast::EsVersion

Should Fix Before Merge:

2. ⚠️ Remove or document unused dependencies
3. ⚠️ Add missing ES2023-2025 modules or remove enum variants
4. ⚠️ Improve TraverseCtx::state documentation with safety notes
5. ⚠️ Add more comprehensive unit tests

Nice to Have:

6. 💡 Consider making TraverseCtx generic over state type
7. 💡 Optimize generate_uid_name to return Atom instead of String
8. 💡 Add a simple no-op hook example to demonstrate composition

---

Compliance with CLAUDE.md

✅ Performance-first: Good use of &str for atoms
✅ English docs: All documentation in English
✅ No unstable features: No nightly-only features used
❌ Unit tests: Minimal coverage, needs more tests
✅ Documentation: Excellent documentation
✅ Formatting: Code passes cargo fmt --check

---

Conclusion

This is a well-architected foundation for an oxc-inspired transformer. The design is sound, documentation is excellent, and the approach of separating infrastructure from implementation is pragmatic.

However, the PR cannot be merged in its current state due to the compilation error from the duplicate EsVersion enum. Once that's fixed and tests pass, this would be a solid foundation for future work.

Recommendation: Request changes - fix the EsVersion issue and add a few more tests before merging.

---

🤖 Generated with Claude Code

[github-actions]

Binary Sizes

File	Size
swc.linux-x64-gnu.node	31M (31928392 bytes)

Commit: 7251925

[codspeed-hq]

CodSpeed Performance Report

Merging #11298 will not alter performance

_{Comparing devbird/oxc-transformer-infrastructure (a5c99c3) with main (c1e32fa)¹}

Summary

✅ 138 untouched

Footnotes

1. No successful run was found on main (0fc7496) during the generation of this report, so c1e32fa was used instead as the comparison base. There might be some changes unrelated to this pull request in this report. ↩

[claude]

Pull Request Review: oxc-inspired transformer infrastructure

Overview

This PR introduces foundational infrastructure for an oxc-inspired transformer implementation built on SWC's visitor patterns. The implementation is well-structured, thoroughly documented, and follows SWC conventions. This is an excellent infrastructure-only PR that sets up the architecture without implementing actual transforms yet.

✅ Strengths

1. Excellent Architecture and Documentation

• The ARCHITECTURE.md file is comprehensive and clearly explains the design decisions, comparisons with oxc, and future roadmap
• Module organization mirrors oxc's structure logically (ES20XX, feature modules, infrastructure)
• Clear separation of concerns between VisitMut and VisitMutHook traits

2. Follows SWC Conventions (CLAUDE.md compliance)

• ✅ Code and documentation in English
• ✅ No unstable/nightly features used
• ✅ Proper use of &str for Atom creation (context.rs:109, 144)
• ✅ Unit tests included for core functionality
• ✅ Clean, well-documented code
• ✅ Performance-first mindset evident in design

3. Good Type Design

• TraverseCtx provides clean API for context management
• TransformOptions structure is comprehensive and extensible
• Proper use of Default derive and serde serialization
• Good use of enums for JsxRuntime and DecoratorVersion

4. Proper Integration

• Uses existing SWC types (Mark, SyntaxContext, EsVersion)
• Leverages swc_ecma_hooks for composability
• Proper dependency management in Cargo.toml
• Tests wrapped in testing::run_test for proper GLOBALS context

5. Incremental Development Approach

• Infrastructure-only approach is wise - establishes patterns before implementing transforms
• Placeholder modules clearly marked with TODO comments
• Second commit shows good responsiveness to CI feedback

📝 Observations & Suggestions

Code Quality

1. TraverseCtx lifetime parameter

pub struct TraverseCtx<'a> {
    state: Option<&'a mut dyn std::any::Any>,
}

The lifetime parameter is only used for the optional state field. This is fine, but consider whether a Box<dyn Any> might be simpler and avoid lifetime complexity. The current design is valid, but the tradeoff should be documented.

2. Unique ID Generation

pub fn generate_uid_name(&mut self, base: &str) -> String {
    self.uid_counter += 1;
    format!("{}_{}", base, self.uid_counter)
}

• Returns String which requires allocation
• Consider whether you need collision avoidance with existing identifiers
• oxc likely has scope-aware name generation - this might need enhancement when scope tracking is added

3. AST Helper Methods
The create_* methods in TraverseCtx use DUMMY_SP for spans. This is reasonable for generated code, but consider:

• Adding a note in documentation that spans should be replaced when source location matters
• Potentially accepting an optional span parameter

4. Module Placeholders
All ES20XX and feature modules are empty placeholders. This is expected for infrastructure, but:

• Consider adding #![allow(unused)] or similar to avoid warnings
• The module structure is good for organization

Testing

Current tests are minimal but appropriate for infrastructure:

• ✅ Tests transformer creation
• ✅ Tests mark handling
• ✅ Tests context creation

Future test recommendations:

• Integration tests once actual transforms are implemented
• Fixture-based testing (comparing input/output)
• Ensure transforms compose correctly via CompositeHook

Documentation

Strong points:

• Comprehensive ARCHITECTURE.md
• Good inline documentation with examples
• Clear comments marking TODOs

Minor improvements:

• Consider adding a high-level example in the crate-level docs showing the intended usage pattern
• Document the transformation order guarantees more explicitly in the main struct docs

Performance Considerations (aligned with CLAUDE.md)

✅ Good practices already in place:

• Using &str for Atoms
• No unnecessary cloning in the infrastructure
• Designed for hook composition without overhead

⚠️ Future considerations:

• Monitor allocation patterns when transforms are implemented
• Consider arena allocation for temporary AST nodes during transformation
• Benchmark against existing swc_ecma_transforms once comparable features are implemented

Security & Safety

No security concerns identified:

• No unsafe code
• Proper use of Rust's type system
• No external inputs processed (yet)
• State management via Any is properly encapsulated

🎯 Specific Recommendations

High Priority (before implementing transforms)

1. Clarify the relationship with existing swc_ecma_transforms

   • Is this intended to replace it eventually?
   • Will they coexist?
   • Add a note in the documentation about this

2. Consider scope tracking architecture

   • The ARCHITECTURE.md mentions missing ancestry tracking
   • Design this before implementing transforms that need it (e.g., arrow functions, classes)

3. Define transform composition strategy

   • Show a concrete example of CompositeHook usage
   • Document ordering guarantees
   • Consider how options enable/disable specific transforms

Medium Priority

4. Add integration examples

   • Show how this crate would be used in a real scenario
   • Demonstrate the full pipeline: parse → transform → codegen

5. Consider adding a builder pattern for TransformOptions

   TransformOptions::builder()
       .target(EsVersion::Es2015)
       .jsx(JsxOptions { enabled: true, .. })
       .build()

6. Document performance expectations

   • What's the overhead of the hook composition?
   • How does context passing affect performance?

Low Priority

7. Consider tracing/instrumentation

   • The crate already imports tracing
   • Add trace points for transform execution to help debugging

8. Bikeshedding: Consider renaming

   • swc_ecma_transformer might be confused with swc_ecma_transforms
   • Consider swc_ecma_transform_hooks or swc_ecma_transform_v2

🚀 Path Forward

This PR is infrastructure-only and ready to merge with minor documentation clarifications. The foundation is solid for implementing actual transforms.

Suggested next steps:

1. Merge this PR to establish the architecture
2. Implement a simple ES2015 transform (e.g., arrow functions) to validate the design
3. Add integration tests and benchmarks
4. Port additional transforms incrementally

📊 Overall Assessment

Category	Rating	Notes
Code Quality	⭐⭐⭐⭐⭐	Clean, well-structured, idiomatic Rust
Documentation	⭐⭐⭐⭐⭐	Excellent docs and architecture guide
Testing	⭐⭐⭐☆☆	Adequate for infrastructure, needs expansion
Performance	⭐⭐⭐⭐☆	Good design, needs validation with real transforms
SWC Conventions	⭐⭐⭐⭐⭐	Follows all CLAUDE.md guidelines
Security	⭐⭐⭐⭐⭐	No concerns

Overall: Strong infrastructure PR that establishes a solid foundation. Ready to merge with confidence! 🎉

---

CI Status Note

I noticed the "Cargo shear" check failed but was addressed in the second commit. Most CI checks are still pending, but the code compiles clean locally with cargo check and all tests pass.

[claude]

Pull Request Review: oxc-inspired transformer infrastructure

Summary

This PR introduces a well-designed foundational infrastructure for an oxc-inspired transformer built on SWC's visitor patterns. The architecture is solid, documentation is comprehensive, and the code follows SWC conventions. This is clearly an infrastructure-only PR with no actual transforms implemented yet.

Strengths

1. Excellent Architecture & Documentation ✅

• ARCHITECTURE.md is exceptionally thorough, explaining design decisions and trade-offs
• Clear comparison between oxc and SWC patterns
• Well-organized module structure mirroring oxc's layout
• Comprehensive inline documentation with examples

2. Clean API Design ✅

• TraverseCtx provides a clean abstraction for transformation utilities
• TransformOptions covers all major transformation categories
• Main Transformer struct has a clear, simple API
• Good separation of concerns between modules

3. Follows SWC Conventions ✅

• Uses &str for Atom creation (per CLAUDE.md guideline Transformers for ecmascript #4)
• Proper use of SyntaxContext and Mark for hygiene
• Implements standard VisitMut trait
• Includes basic unit tests

4. Performance-Conscious Design ✅

• Follows CLAUDE.md guideline ecmascript parser #1: "Write performant code"
• Minimal allocations in helper methods
• Uses #[inline] on hot-path accessors
• Counter-based UID generation (no hashing overhead)

Issues & Concerns

1. Missing cargo fmt verification ⚠️

CLAUDE.md guideline #8: "Run cargo fmt --all before committing files"

The code appears well-formatted, but this should be verified before merge:

cargo fmt --all --check

2. Incomplete test coverage ⚠️

CLAUDE.md guideline #5: "Write unit tests for your code"

Current tests only cover:

• Transformer creation
• Mark handling
• Context creation

Missing tests:

• TraverseCtx helper methods (generate_uid_name, create_ident_expr, etc.)
• State management (set_state, state, state_mut)
• Edge cases (e.g., multiple UID generation, empty contexts)

Recommendation: Add unit tests for all public APIs in TraverseCtx:

#[test]
fn test_generate_uid_name() {
    let mut ctx = TraverseCtx::default();
    assert_eq!(ctx.generate_uid_name("temp"), "temp_1");
    assert_eq!(ctx.generate_uid_name("temp"), "temp_2");
    assert_eq!(ctx.generate_uid_name("foo"), "foo_3");
}

#[test]
fn test_create_ident_expr() {
    let ctx = TraverseCtx::default();
    let expr = ctx.create_ident_expr("foo", DUMMY_SP);
    match expr {
        Expr::Ident(ident) => {
            assert_eq!(ident.sym.as_str(), "foo");
            assert_eq!(ident.ctxt, ctx.unresolved_ctxt());
        }
        _ => panic!("Expected Ident"),
    }
}

#[test]
fn test_state_management() {
    let mut ctx = TraverseCtx::default();
    let mut state = 42i32;
    ctx.set_state(&mut state);
    assert!(ctx.state().is_some());
    assert_eq!(*ctx.state_mut().unwrap().downcast_ref::<i32>().unwrap(), 42);
}

3. Potential lifetime issue in TraverseCtx 🔍

File: crates/swc_ecma_transformer/src/context.rs:41

The state field uses Option<&'a mut dyn std::any::Any>, but the lifetime 'a is never constrained. This works for now but might cause issues when:

• Composing hooks that share state
• State needs to outlive the context

Current code (context.rs:41):

state: Option<&'a mut dyn std::any::Any>,

This is likely fine for the infrastructure phase, but worth monitoring as transforms are implemented.

4. Missing documentation on default values 📝

File: crates/swc_ecma_transformer/src/options.rs

Several option structs implement Default but don't document what the defaults are:

• TransformOptions::default() - What's the default target?
• JsxOptions::default() - What's pragma when None?

Suggestion: Add doc comments explaining defaults:

/// # Defaults
/// - `target`: `EsVersion::Es5`
/// - `typescript.enabled`: `false`
/// - `jsx.enabled`: `false`
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct TransformOptions {
    // ...
}

5. Unused module warnings 🔇

All ES20XX and feature modules are empty placeholder modules. While this is expected for infrastructure, consider:

• Adding #![allow(dead_code)] at module level to suppress warnings during development
• Or adding minimal stub implementations (e.g., empty struct types)

Example:

//! ES2015 (ES6) transformations.
#![allow(dead_code)]  // Remove when transforms are implemented

// TODO: Implement ES2015 transforms

6. No integration with existing SWC transforms 🤔

Question: How will this new transformer infrastructure relate to existing transforms in swc_ecma_transforms?

• Will this replace existing transforms?
• Will they coexist?
• Is there a migration plan?

This should be clarified in ARCHITECTURE.md or the PR description.

Code Quality

Positive Observations ✅

• Clean, idiomatic Rust code
• Good use of inline documentation
• Proper visibility controls (private fields, public methods)
• No clippy warnings (with #![deny(clippy::all)])
• Clear separation between interface and implementation

Minor Style Suggestions 💡

1. Consistency in doc comments (lib.rs:88-99):
   The transformation order list uses numbers 1-6, but there are only 6 items. Consider using a clearer format:

   /// 1. TypeScript transforms (layer x0)
   /// 2. JSX transforms (layer x1)
   /// 3. Decorator transforms (layer x1)
   /// 4. ES20XX transforms (layers x2-x4, reverse chronological)
   /// 5. RegExp transforms (layer x4)
   /// 6. Common transforms (layer x4)
   

2. Consider adding Debug output helpers:
   For TraverseCtx, consider implementing Debug manually to avoid exposing dyn Any:

   impl<'a> std::fmt::Debug for TraverseCtx<'a> {
       fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
           f.debug_struct("TraverseCtx")
               .field("unresolved_ctxt", &self.unresolved_ctxt)
               .field("top_level_ctxt", &self.top_level_ctxt)
               .field("uid_counter", &self.uid_counter)
               .field("state", &self.state.as_ref().map(|_| "Some(<state>)"))
               .finish()
       }
   }

Security & Safety ✅

No security concerns identified:

• No unsafe code
• No external dependencies beyond SWC ecosystem
• Proper use of visibility controls
• No file I/O or network operations

Performance Considerations ✅

The design is performance-conscious:

• Uses #[inline] on getters (context.rs:65, 74, lib.rs:177-190)
• Minimal allocations (uses &str for Atoms)
• Simple counter-based UID generation
• No unnecessary cloning

Note: Actual performance impact can only be measured once transforms are implemented.

Documentation Quality ✅

Documentation is excellent:

• ARCHITECTURE.md: Comprehensive, well-structured, includes roadmap
• Module docs: Clear descriptions of future plans
• Function docs: Examples and explanations

Suggestion: Consider adding a top-level CONTRIBUTING.md with guidelines for:

• How to implement a new transform
• Testing requirements
• How to compose hooks

Test Strategy

Current tests are minimal but appropriate for infrastructure. As transforms are implemented, ensure:

1. Unit tests for each transform (per CLAUDE.md Handle early errors in ecmascript parser #5)
2. Fixture tests comparing input/output code
3. Integration tests with composed hook chains
4. Compatibility tests vs Babel/TypeScript/oxc where applicable

Recommendations

Before Merge (High Priority)

1. ✅ Run cargo fmt --all and verify formatting
2. ⚠️ Add unit tests for TraverseCtx helper methods
3. 📝 Document default values in TransformOptions
4. 🤔 Clarify relationship with existing swc_ecma_transforms in docs

Future PRs (Medium Priority)

5. Add #![allow(dead_code)] to placeholder modules
6. Consider implementing Debug for TraverseCtx
7. Add CONTRIBUTING.md with transform implementation guidelines
8. Add fixture test infrastructure for future transforms

Long-term Considerations

9. Monitor the lifetime design in TraverseCtx::state
10. Benchmark performance vs existing SWC transforms once implemented
11. Consider adding ancestry tracking (mentioned in ARCHITECTURE.md)

Verdict

Recommendation: Approve with minor revisions ✅

This is a high-quality infrastructure PR that:

• ✅ Follows SWC conventions (mostly)
• ✅ Is well-documented
• ✅ Has a clear architectural vision
• ✅ Sets up a solid foundation for future work

Required before merge:

1. Run cargo fmt --all
2. Add unit tests for TraverseCtx helper methods

Nice to have:
3. Document default values
4. Clarify integration strategy with existing transforms

The infrastructure is solid and ready to support the implementation of actual transforms in subsequent PRs. Great work on the architecture and documentation!

---

Review generated with assistance from Claude Code

[claude]

Pull Request Review: oxc-inspired transformer infrastructure

Overview

This PR introduces foundational infrastructure for an oxc-inspired transformer implementation. The code is well-structured and follows SWC conventions. Here's my detailed review:

✅ Strengths

1. Excellent Documentation

• Comprehensive ARCHITECTURE.md that clearly explains design decisions
• Well-documented code with rustdoc comments on all public APIs
• Clear examples in documentation (using ignore directive appropriately)
• Good comparison tables between oxc and SWC approaches

2. Solid Architecture

• Clean separation between infrastructure and implementation
• Proper use of SWC's VisitMut + VisitMutHook pattern
• Composable design that mirrors oxc's successful architecture
• Well-organized module structure with clear separation of concerns

3. Follows SWC Conventions ✓

• Uses &str for Atom creation (as per CLAUDE.md point 4)
• Includes unit tests (CLAUDE.md point 5)
• Written in English documentation (CLAUDE.md point 2)
• No unstable/nightly features used (CLAUDE.md point 3)
• Properly formatted with cargo fmt

4. Good Test Coverage for Infrastructure

• Basic unit tests verify transformer creation
• Tests properly wrapped in testing::run_test for GLOBALS context
• Tests verify mark handling and context creation
• All tests passing successfully

📋 Observations & Suggestions

1. Performance Considerations (CLAUDE.md point 1: "prefer performance over other things")

The code is already performance-conscious, but here are some areas to watch as actual transforms are implemented:

• TraverseCtx::generate_uid_name (line 90-93 in context.rs) uses format! which allocates. Consider using a more efficient approach if this becomes hot path:

• The uid_counter could potentially overflow on very long-running transforms. Consider using a larger type or wrapping strategy.

2. Potential Memory Efficiency

• TraverseCtx::state uses Option<&'a mut dyn Any> which is fine for flexibility, but consider if a more constrained generic approach could avoid the dynamic dispatch overhead once use cases are clearer.

3. API Design Thoughts

context.rs line 109: Using .into() for Atom creation is good, but ensure consistency. All the helper methods follow the pattern correctly.

context.rs lines 181-194: The state accessor methods could benefit from downcasting helpers:

This would make the API more ergonomic for transform implementations.

4. Future Robustness

• Consider adding #[non_exhaustive] to option structs if you anticipate adding more fields without breaking changes
• The placeholder modules are all marked // TODO which is good, but consider adding module-level tests as transforms are implemented

5. Documentation Completeness

The ignored doctests are appropriate since they require full compilation context. Consider adding a note explaining why they're ignored:

6. Type Safety

The use of DUMMY_SP in helper methods (context.rs lines 140, 142-144, 160, 162) is pragmatic, but downstream transforms should be encouraged to provide real spans for better error messages. Consider adding this to documentation.

🔒 Security Considerations

✅ No security concerns identified:

• No unsafe code blocks
• No network operations
• No file I/O in infrastructure code
• No user input handling at this layer
• Proper use of syntax contexts prevents identifier collision issues

🐛 Potential Bugs/Issues

Minor: Atom Creation Pattern

While the code follows the guideline to use &str for Atom creation, there's a slight inefficiency potential. The .into() calls create temporary allocations. This is minor and acceptable, but worth noting for hot paths in future transforms.

Context: Missing Validation

TraverseCtx::new doesn't validate that the contexts are actually different. While tests verify they're different, consider adding a debug assertion:

🎯 Test Coverage

Current Status: ✅ Good for infrastructure layer

• Basic creation tests ✓
• Mark handling tests ✓
• Context creation tests ✓

Future Needs (as noted in PR):

• Integration tests for composed transformation pipelines
• Fixture tests comparing with expected output
• Performance benchmarks against existing SWC transforms

📦 Dependencies

✅ Dependency hygiene is excellent:

• All unused dependencies removed (cargo shear passing)
• Minimal dependency footprint
• Only necessary features enabled
• Proper use of workspace dependencies

🎨 Code Quality

Overall: Excellent

• Clean, idiomatic Rust
• Consistent naming conventions
• Proper visibility modifiers
• No clippy warnings (would need clippy installed to verify all, but manual review shows good practices)
• Good use of inline attributes for hot-path functions

📝 Recommendations for Phase 2+

When implementing actual transforms:

1. Add comprehensive fixture tests - Compare output with babel/typescript/oxc where applicable
2. Benchmark against existing SWC transforms - Ensure the composable architecture doesn't introduce overhead
3. Consider adding tracing - The dependency was removed (correctly, as unused), but may be valuable for debugging complex transform chains
4. Implement ancestry tracking - Mentioned in ARCHITECTURE.md as future work; this will be important for many transforms
5. Add transform ordering validation - Ensure transforms are applied in the documented order
6. Consider adding a transform registry - For dynamic transform composition based on options

✨ Summary

This is high-quality foundational work that sets up an excellent base for future development. The architecture is sound, documentation is thorough, and it properly adapts oxc's design to SWC's patterns.

Approval: ✅ Recommend Approval

Rationale:

• Follows all SWC conventions from CLAUDE.md
• No actual transforms means low risk of introducing bugs
• Infrastructure compiles cleanly and all tests pass
• Well-documented design makes future development clear
• No security concerns
• Good architectural decisions

Action Items (Non-blocking):

1. Consider adding downcast helpers for state access (ergonomics)
2. Add span usage guidelines to documentation (quality)
3. Consider debug assertions for context validity (safety)
4. Document why doctests are ignored (clarity)

Excellent work on this infrastructure! Looking forward to seeing the actual transforms in future PRs. 🚀

---

Review generated with assistance from Claude Code

[Copilot]

Pull Request Overview

This PR introduces foundational infrastructure for an oxc-inspired transformer built on SWC's visitor patterns. It establishes a composable hook-based architecture for JavaScript/TypeScript transformations with context management utilities, comprehensive configuration options, and an organized module structure for future transform implementations.

Key changes:

• New swc_ecma_transformer crate with Transformer struct implementing VisitMut
• TraverseCtx context type providing syntax context management, unique ID generation, and AST building helpers
• Comprehensive configuration types (TransformOptions, JsxOptions, TypeScriptOptions, etc.)

Reviewed Changes

Copilot reviewed 21 out of 22 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
crates/swc_ecma_transformer/Cargo.toml	Package manifest defining dependencies for the new transformer crate
crates/swc_ecma_transformer/src/lib.rs	Main transformer implementation with Transformer struct and module declarations
crates/swc_ecma_transformer/src/context.rs	TraverseCtx implementation providing utilities for transformations
crates/swc_ecma_transformer/src/options.rs	Configuration types for controlling transformer behavior
crates/swc_ecma_transformer/src/es20XX/mod.rs	Placeholder modules for ECMAScript version-specific transforms
crates/swc_ecma_transformer/src/{jsx,typescript,decorator,regexp}/mod.rs	Placeholder modules for feature-specific transforms
crates/swc_ecma_transformer/src/{common,proposals,utils}/mod.rs	Placeholder modules for infrastructure and utilities
crates/swc_ecma_transformer/ARCHITECTURE.md	Comprehensive documentation of the transformer architecture and design
Cargo.lock	Lock file update adding the new crate

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Missing module declarations for ES2023 and ES2024. The EsVersion enum in swc_ecma_ast includes Es2023 and Es2024 variants. The code should declare pub mod es2023; and pub mod es2024; between es2022 and es2026 to maintain consistency with the ECMAScript versioning scheme, even if these modules are currently placeholders.

Suggested change

	pub mod es2022;
	pub mod es2022;
	pub mod es2023;
	pub mod es2024;