docs: Add TC39 ECMA-426 scopes proposal implementation design
This commit introduces a comprehensive design document for implementing
the TC39 ECMA-426 scopes proposal in SWC. The scopes proposal extends
source maps to include scope information (variable bindings, function
boundaries, scope hierarchies), enabling debuggers to provide accurate
variable inspection even after aggressive optimizations.
## Design Highlights
### Architecture Analysis
- Analyzed SWC's existing source map infrastructure (SourceMap, JsWriter)
- Documented current scope tracking via Resolver pass
- Identified position tracking during code generation
- Reviewed AST visitor patterns (Visit, VisitMut, Fold)
### TC39 Specification Research
- Studied original scope and generated range data structures
- Documented VLQ encoding format with 8 tag types (B-I)
- Analyzed delta encoding strategy for position optimization
- Reviewed Chrome DevTools encoding recommendations
### Implementation Design
- Designed Rust data structures for OriginalScope and GeneratedRange
- Created ScopeCollector visitor for scope information collection
- Designed RangeTracker for tracking generated code ranges
- Implemented VLQ encoder with delta encoding support
### Integration Strategy
- Zero-overhead design using feature flags (sourcemap-scopes)
- Leverages existing Resolver infrastructure to avoid duplication
- Integrates with current source map generation pipeline
- Phased implementation plan (12 weeks, 6 phases)
### Performance Considerations
- Feature flag ensures no overhead when disabled
- Memory overhead: ~48 bytes per scope (0.024% for typical files)
- Target: <5% performance impact when enabled
- Optimized VLQ encoding with delta compression
## Key Design Decisions
1. **New Crate**: Create `swc_sourcemap_scopes` crate for isolation
2. **Visitor Pattern**: Use existing Visit trait for scope collection
3. **Feature Flags**: Conditional compilation for zero overhead
4. **Arena Allocation**: Consider bumpalo for scope tree allocation
5. **Interning**: Leverage existing Atom interning for scope names
## Implementation Phases
1. Foundation: Data structures and VLQ encoder (Week 1-2)
2. Scope Collection: Implement collector visitor (Week 3-4)
3. Range Tracking: Modify Emitter for tracking (Week 5-6)
4. Encoding: Full scopes encoding integration (Week 7-8)
5. Optimization: Performance tuning and docs (Week 9-10)
6. Advanced Features: Bindings and callsites (Week 11-12)
## References
- TC39 ECMA-426 Scopes Proposal
- ECMA-426 Source Map Specification
- Chrome DevTools Scopes Encoding
- SWC Resolver and SourceMap documentation
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
9428791
4 days ago
by github-actions[bot]
-0.01%
docs: Move scopes design to ADR format
Restructure the TC39 ECMA-426 scopes proposal design document to follow
the Architecture Decision Record (ADR) format as requested in review.
Changes:
- Move from docs/sourcemap-scopes-design.md to docs/adr/00005-tc39-ecma426-scopes-proposal-implementation.md
- Restructure content to follow ADR template with Context/Problem, Decision Drivers, Options, and Decision Outcome sections
- Maintain all technical details including data structures, integration points, and implementation phases
- Add proper ADR metadata (status: proposed, date, deciders)
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
8ed6136
4 days ago
by github-actions[bot]
+0.01%
fix(ci): Ignore RUSTSEC-2026-0001 for rkyv 0.7.45
The rkyv 0.7.45 vulnerability (RUSTSEC-2026-0001) is a transitive
dependency from parcel_sourcemap via lightningcss. The vulnerability
involves potential undefined behavior in Arc<T>/Rc<T> implementations
during OOM (Out of Memory) conditions, which is unlikely to occur in
normal usage.
This is being ignored until parcel_sourcemap updates their rkyv
dependency to a patched version.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>