Skip to content

Commit f1862c4

Browse files
BoshenBoshen
committed
docs(minifier): add comprehensive documentation for oxc_minifier (#13938)
Goal of this PR is too feed AI with more context. ## Summary Add extensive documentation to guide development of the world's best JavaScript minifier. ## Documentation Added ### New Files - **ARCHITECTURE.md**: Design philosophy and component overview - **OPTIMIZATIONS.md**: Catalog of all 17 current optimizations and planned additions - **ASSUMPTIONS.md**: Document code assumptions for safe optimizations - **CORRECTNESS.md**: Testing strategies and validation guarantees - **ROADMAP.md**: Development phases and success metrics - **CLAUDE.md**: AI assistant guide for development ### Updated Files - **README.md**: Updated with features, testing infrastructure, and documentation links - **src/lib.rs**: Enhanced module documentation with examples ## Goals This documentation establishes the vision for oxc_minifier: - 🎯 **Smallest output size** (beat Closure Compiler) - ✅ **100% correctness** (full test suite compliance) - ⚡ **Reasonable performance** (competitive with esbuild) ## Inspiration Learning from industry leaders: - Closure Compiler (advanced size optimizations) - Terser/UglifyJS (comprehensive battle-tested transforms) - esbuild (efficient algorithms) - SWC (modern Rust architecture) ## Benefits - Clear development roadmap - Comprehensive optimization documentation - AI-friendly development guide - Testing and correctness guarantees - Documented assumptions for safe optimizations 🤖 Generated with [Claude Code](https://claude.ai/code)
1 parent a564d2d commit f1862c4

File tree

8 files changed

+1180
-35
lines changed

8 files changed

+1180
-35
lines changed

‎crates/oxc_minifier/README.md‎

Lines changed: 47 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -1,47 +1,60 @@
1-
# Minifier
1+
# Oxc Minifier
22

3-
A JavaScript minifier has three components:
3+
Next-generation JavaScript/TypeScript minifier achieving best-in-class compression.
44

5-
1. compressor
6-
2. mangler
7-
3. printer
5+
## Inspiration
86

9-
## Compressor
7+
- **Closure Compiler**: Advanced size optimizations
8+
- **Terser/UglifyJS**: Comprehensive battle-tested transforms
9+
- **esbuild**: Efficient algorithms and architecture
10+
- **SWC**: Modern Rust performance
1011

11-
The compressor is responsible for rewriting statements and expressions for minimal text output.
12-
[Terser](https://github.com/terser/terser) is a good place to start for learning the fundamentals.
12+
## Key Features
1313

14-
## Mangler
14+
- Maximum compression through exhaustive optimizations
15+
- 100% correctness with comprehensive testing
16+
- Fixed-point iteration for optimal size
17+
- Arena allocation for performance
1518

16-
The mangler implementation is part of the `SymbolTable` residing in `oxc_semantic`.
17-
It is responsible for shortening variables. Its algorithm should be gzip friendly.
19+
## Current Performance
1820

19-
The printer is also responsible for printing out the shortened variable names.
21+
See [`tasks/minsize`](../../tasks/minsize) for compression benchmarks.
2022

21-
## Printer
23+
- Matching/beating esbuild on many libraries
24+
- Full test262, Babel, TypeScript conformance
2225

23-
The printer is responsible for removing whitespace from the source text.
26+
## Usage
2427

25-
### Assumptions
28+
```rust
29+
use oxc_minifier::{Minifier, MinifierOptions};
2630

27-
- [Properties of the global object defined in the ECMAScript spec](https://tc39.es/ecma262/multipage/global-object.html#sec-global-object) behaves the same as in the spec
28-
- Examples of properties: `Infinity`, `parseInt`, `Object`, `Promise.resolve`
29-
- Examples that breaks this assumption: `globalThis.Object = class MyObject {}`
30-
- The code does not rely on the `name` property of `Function` or `Class`
31-
- Examples that breaks this assumption: `function fn() {}; console.log(f.name === 'fn')`
32-
- [`document.all`](https://tc39.es/ecma262/multipage/additional-ecmascript-features-for-web-browsers.html#sec-IsHTMLDDA-internal-slot) is not used or behaves as a normal object
33-
- Examples that breaks this assumption: `console.log(typeof document.all === 'undefined')`
34-
- TDZ violation does not happen
35-
- Examples that breaks this assumption: `(() => { console.log(v); let v; })()`
36-
- `with` statement is not used
37-
- Examples that breaks this assumption: `with (Math) { console.log(PI); }`
38-
- `.toString()`, `.valueOf()`, `[Symbol.toPrimitive]()` are side-effect free
39-
- Examples that breaks this assumption: `{ toString() { console.log('sideeffect') } }`
40-
- Errors thrown when creating a String or an Array that exceeds the maximum length can disappear or moved
41-
- Examples that breaks this assumption: `try { new Array(Number(2n**53n)) } catch { console.log('log') }`
42-
- Extending a class does not have a side effect
43-
- Examples that breaks this assumption: `const v = []; class A extends v {}`
31+
let options = MinifierOptions::default();
32+
let minifier = Minifier::new(options);
33+
let result = minifier.minify(&mut program);
34+
```
4435

45-
## Terser Tests
36+
## Testing Infrastructure
4637

47-
The fixtures are copied from https://github.com/terser/terser/tree/v5.9.0/test/compress
38+
- `just minsize` - Track compression benchmarks
39+
- `cargo coverage` - Conformance tests (test262, Babel, TypeScript)
40+
- `tasks/e2e` - Real-world E2E testing
41+
42+
## Development
43+
44+
- `just test` - Run all tests
45+
- `cargo run -p oxc_minifier --example minifier` - Try the minifier
46+
47+
## Key Dependencies
48+
49+
- [`oxc_ecmascript`](../oxc_ecmascript) - ECMAScript operations and constant evaluation
50+
- [`oxc_semantic`](../oxc_semantic) - Scope and symbol analysis
51+
- [`oxc_mangler`](../oxc_mangler) - Variable renaming
52+
53+
## Documentation
54+
55+
- [Architecture](./docs/ARCHITECTURE.md) - Design and components
56+
- [Optimizations](./docs/OPTIMIZATIONS.md) - Complete optimization catalog
57+
- [Assumptions](./docs/ASSUMPTIONS.md) - Code assumptions for optimization
58+
- [Correctness](./docs/CORRECTNESS.md) - Testing and validation
59+
- [Roadmap](./docs/ROADMAP.md) - Development plan
60+
- [Claude Guide](./docs/CLAUDE.md) - AI assistant reference

‎crates/oxc_minifier/docs/ARCHITECTURE.md‎

Lines changed: 145 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,145 @@
1+
# Architecture
2+
3+
## Design Philosophy
4+
5+
Achieve maximum compression through comprehensive optimizations while maintaining correctness.
6+
7+
### Size Optimization Strategy
8+
9+
- Fixed-point iteration until no more improvements
10+
- Combine multiple optimization techniques
11+
- Learn from all major minifiers
12+
- Apply optimizations exhaustively
13+
14+
### Learning from Industry Leaders
15+
16+
#### From Closure Compiler (Size Focus)
17+
18+
- Advanced dead code elimination
19+
- Aggressive constant folding
20+
- Cross-statement optimizations
21+
- Property flattening techniques
22+
- Whole program analysis
23+
24+
#### From Terser/UglifyJS (Comprehensive)
25+
26+
- All peephole optimizations
27+
- Battle-tested patterns
28+
- Edge case handling
29+
- Extensive transformation catalog
30+
31+
#### From esbuild (Performance)
32+
33+
- Minimal AST passes where possible
34+
- Arena allocation strategy
35+
- Efficient algorithms
36+
- Smart traversal patterns
37+
38+
#### From SWC (Modern)
39+
40+
- Rust safety and performance
41+
- Clean visitor pattern
42+
- Parallel processing potential
43+
- Modern architecture
44+
45+
## Core Components
46+
47+
### Compressor (`compressor.rs`)
48+
49+
Orchestrates the optimization pipeline with fixed-point iteration.
50+
51+
```rust
52+
pub struct Compressor<'a> {
53+
allocator: &'a Allocator,
54+
}
55+
```
56+
57+
Key responsibilities:
58+
59+
- Builds semantic model
60+
- Applies normalization
61+
- Runs peephole optimizations to fixed-point
62+
- Manages optimization state
63+
64+
### Peephole Optimizations (`peephole/`)
65+
66+
17+ transformation passes including:
67+
68+
- Constant folding
69+
- Dead code elimination
70+
- Control flow optimization
71+
- Expression simplification
72+
- Syntax substitution
73+
74+
Each optimization implements transformations in the AST traversal visitor pattern.
75+
76+
### Context (`ctx.rs`)
77+
78+
Shared utilities for optimizations:
79+
80+
- AST manipulation helpers
81+
- Constant evaluation
82+
- Side effect analysis
83+
- Semantic utilities
84+
85+
```rust
86+
pub struct Ctx<'a, 'b> {
87+
// Provides access to:
88+
// - AST builder
89+
// - Scoping information
90+
// - Symbol values
91+
// - Optimization options
92+
}
93+
```
94+
95+
### State Management (`state.rs`)
96+
97+
Tracks optimization state:
98+
99+
- Symbol values
100+
- Changed flags
101+
- Pure functions
102+
- Source type
103+
104+
## Optimization Pipeline
105+
106+
```
107+
1. Parse and Build Semantic Model
108+
└─> SemanticBuilder creates scoping and symbols
109+
110+
2. Normalization Pass
111+
└─> Convert to canonical form for optimizations
112+
113+
3. Peephole Optimization Loop
114+
└─> Apply all optimizations
115+
└─> Check if any changes made
116+
└─> Repeat until fixed-point (no changes)
117+
118+
4. Optional Mangling
119+
└─> Rename variables for size
120+
121+
5. Code Generation
122+
└─> Output optimized JavaScript
123+
```
124+
125+
## Memory Management
126+
127+
- Arena allocation via `oxc_allocator`
128+
- Minimal cloning through `TakeIn` trait
129+
- Efficient AST manipulation with arena pointers
130+
131+
## Traversal Strategy
132+
133+
Using `oxc_traverse` for AST walking:
134+
135+
- Enter/exit hooks for each node type
136+
- Bottom-up transformations (exit handlers)
137+
- State tracking through context
138+
139+
## Integration Points
140+
141+
- `oxc_ast`: AST node definitions
142+
- `oxc_semantic`: Scope and symbol analysis
143+
- `oxc_ecmascript`: ECMAScript operations
144+
- `oxc_mangler`: Variable renaming
145+
- `oxc_codegen`: Output generation

0 commit comments

Comments
 (0)