docs(rust): Add comprehensive README.md documentation for all Rust crates

crates/oxc_allocator/README.md

@@ -0,0 +1,29 @@
+# Oxc Allocator
+
+A high-performance memory allocator using bump-based arena allocation for fast AST node creation.
+
+## Overview
+
+Oxc uses a bump-based memory arena for faster AST allocations. This crate provides an [`Allocator`] that manages memory efficiently by allocating objects in a single contiguous memory region, avoiding the overhead of individual heap allocations.
+
+## Key Features
+
+- **Bump allocation**: Fast allocation by simply incrementing a pointer
+- **Arena-based memory management**: All allocations live for the same lifetime
+- **Zero-copy data structures**: Efficient `Box`, `Vec`, `String`, and `HashMap` implementations
+- **Optimal for AST operations**: Perfect for parse-transform-emit workflows
+
+## Architecture
+
+The allocator is designed specifically for AST processing workflows where:
+
+1. A large number of nodes are allocated during parsing
+2. All nodes have the same lifetime (tied to the AST)
+3. Memory is released all at once when the AST is dropped
+
+This approach is significantly faster than using the system allocator for AST operations.
+
+## Features
+
+- `serialize` - Enables serialization support for `Box` and `Vec` with `serde`
+- `from_raw_parts` - Adds unsafe `from_raw_parts` method (not recommended for general use)

crates/oxc_ast/README.md

@@ -0,0 +1,35 @@
+# Oxc AST
+
+Abstract Syntax Tree definitions for JavaScript, TypeScript, and JSX.
+
+## Overview
+
+This crate provides comprehensive AST (Abstract Syntax Tree) node definitions that support the full spectrum of JavaScript and TypeScript syntax, including JSX. The AST closely follows ECMAScript specifications while providing ergonomic APIs for manipulation.
+
+## Key Features
+
+- **Complete language support**: JavaScript, TypeScript, JSX, and TSX
+- **ECMAScript compliant**: AST structure follows official specifications
+- **Memory efficient**: Designed to work with `oxc_allocator` for fast allocation
+- **Visitor patterns**: Integrates with `oxc_ast_visit` for traversal
+- **Type-safe**: Leverages Rust's type system for correctness
+
+## AST Design Principles
+
+The AST design differs from estree in several important ways:
+
+- **Explicit identifiers**: Uses specific types like `BindingIdentifier`, `IdentifierReference`, and `IdentifierName` instead of generic `Identifier`
+- **Precise assignment targets**: `AssignmentExpression.left` uses `AssignmentTarget` instead of generic `Pattern`
+- **Literal specialization**: Replaces generic `Literal` with `BooleanLiteral`, `NumericLiteral`, `StringLiteral`, etc.
+- **Evaluation order**: Field order follows ECMAScript evaluation order for consistency
+
+## Architecture
+
+The AST is designed for:
+
+- **Parse**: Efficient construction during parsing
+- **Transform**: Easy manipulation during transpilation
+- **Visit**: Systematic traversal for analysis
+- **Codegen**: Clean conversion back to source code
+
+All AST nodes are allocated in an arena (`oxc_allocator`) for optimal performance.

crates/oxc_ast_macros/README.md

@@ -0,0 +1,32 @@
+# Oxc AST Macros
+
+Procedural macros for generating AST-related code and ensuring memory layout consistency.
+
+## Overview
+
+This crate provides procedural macros that generate boilerplate code for AST nodes, ensuring consistent memory layout and providing derived traits automatically.
+
+## Key Features
+
+- **`#[ast]` attribute**: Marks types as AST nodes and generates required traits
+- **Memory layout control**: Ensures `#[repr(C)]` for predictable memory layout
+- **Trait derivation**: Automatically derives common traits like `Debug`, `Clone`, etc.
+- **Code generation**: Reduces boilerplate and ensures consistency across AST types
+
+## What the `#[ast]` Macro Does
+
+1. **Adds `#[repr(C)]`**: Ensures predictable memory layout across platforms
+2. **Marker for tooling**: Identifies types as AST nodes for code generation tools
+3. **Trait derivation**: Automatically implements common traits
+4. **Consistency**: Ensures all AST nodes follow the same patterns
+
+## Architecture
+
+This macro system enables:
+
+- **Maintainable AST**: Reduces boilerplate across hundreds of AST types
+- **Consistent layout**: Critical for performance and correctness
+- **Tool integration**: Allows `oxc_ast_tools` to generate visitor code
+- **Type safety**: Ensures all AST nodes have required traits
+
+The macros are designed to be transparent and generate minimal, efficient code.

crates/oxc_ast_visit/README.md

@@ -0,0 +1,25 @@
+# Oxc AST Visit
+
+Visitor pattern implementations for traversing and mutating AST nodes.
+
+## Overview
+
+This crate provides visitor traits and implementations for systematically traversing AST nodes. It supports both immutable visitation (`Visit`) and mutable transformation (`VisitMut`).
+
+## Key Features
+
+- **`Visit` trait**: Immutable AST traversal for analysis
+- **`VisitMut` trait**: Mutable AST traversal for transformations
+- **Generated implementations**: Most visitor code is auto-generated for consistency
+- **UTF-8 to UTF-16 conversion**: Special visitors for span conversion
+
+## Architecture
+
+The visitor pattern is designed for:
+
+- **Analysis**: Static analysis, linting, and code inspection
+- **Transformation**: Code modification and transpilation
+- **Consistency**: Systematic traversal of all AST nodes
+- **Performance**: Efficient traversal with minimal overhead
+
+Most visitor implementations are generated by `oxc_ast_tools` to ensure all AST nodes are covered and traversal is consistent.

crates/oxc_cfg/README.md

@@ -0,0 +1,40 @@
+# Oxc CFG
+
+Control Flow Graph construction and analysis for JavaScript and TypeScript.
+
+## Overview
+
+This crate provides data structures and algorithms for building and analyzing Control Flow Graphs (CFGs) from AST nodes. CFGs are essential for advanced static analysis, optimization, and understanding program flow.
+
+## Key Features
+
+- **CFG construction**: Build control flow graphs from AST nodes
+- **Block-based representation**: Organizes code into basic blocks
+- **Graph analysis**: Traverse and analyze control flow patterns
+- **DOT export**: Visualize CFGs using Graphviz dot format
+- **Visitor integration**: Works with oxc visitor patterns
+
+## Architecture
+
+### Basic Blocks
+
+The CFG organizes code into basic blocks - sequences of instructions with:
+
+- Single entry point (first instruction)
+- Single exit point (last instruction)
+- No internal branches or jumps
+
+### Graph Structure
+
+- **Nodes**: Basic blocks containing instructions
+- **Edges**: Control flow between blocks (conditional, unconditional, exception)
+- **Entry/Exit**: Special blocks for function entry and exit points
+
+### Analysis Applications
+
+- **Dead code elimination**: Find unreachable blocks
+- **Data flow analysis**: Track variable usage across control paths
+- **Loop detection**: Identify back edges and loop structures
+- **Path analysis**: Enumerate possible execution paths
+
+The CFG integrates with semantic analysis to provide comprehensive program understanding.

crates/oxc_codegen/README.md

@@ -0,0 +1,33 @@
+# Oxc Codegen
+
+High-performance code generation from AST back to JavaScript/TypeScript source code.
+
+## Overview
+
+This crate converts AST nodes back into source code strings, supporting JavaScript, TypeScript, and JSX. It's designed for speed and correctness, producing clean, readable output.
+
+## Key Features
+
+- **Fast code generation**: Optimized for performance with minimal allocations
+- **Source map support**: Generate accurate source maps during output
+- **Configurable formatting**: Control whitespace, semicolons, and other formatting options
+- **Comment preservation**: Maintain comments during code generation
+- **Binary expression optimization**: Intelligent parentheses insertion
+
+## Architecture
+
+### Code Generation Pipeline
+
+1. **AST Traversal**: Walk through AST nodes systematically
+2. **Token Generation**: Convert nodes to appropriate tokens/strings
+3. **Formatting**: Apply whitespace, indentation, and style rules
+4. **Source Mapping**: Track original source positions if enabled
+
+### Design Principles
+
+- **Correctness**: Generated code must be functionally equivalent to original
+- **Performance**: Minimize string allocations and copying
+- **Readability**: Produce clean, well-formatted output
+- **Fidelity**: Preserve semantic meaning and behavior
+
+The codegen is adapted from esbuild's approach, optimized for Rust and oxc's AST structure.

crates/oxc_data_structures/README.md

@@ -0,0 +1,26 @@
+# Oxc Data Structures
+
+Common data structures and utilities used across oxc crates.
+
+## Overview
+
+This crate provides specialized data structures and utilities that are used throughout the oxc toolchain. These structures are optimized for the specific needs of compiler and tooling workloads.
+
+## Key Features
+
+- **Code buffer**: Efficient string building with segment tracking
+- **Inline strings**: Memory-efficient string storage for short strings
+- **Pointer extensions**: Utilities for safe pointer manipulation
+- **Slice iterators**: Enhanced iteration capabilities for slices
+- **Rope data structure**: Efficient text manipulation for large documents
+
+## Architecture
+
+These data structures are designed with specific compiler requirements in mind:
+
+- **Performance**: Optimized for common patterns in parsing and code generation
+- **Memory efficiency**: Minimize allocations and memory overhead
+- **Safety**: Provide safe abstractions over potentially unsafe operations
+- **Ergonomics**: Easy to use APIs that integrate well with other oxc components
+
+The structures complement Rust's standard library with domain-specific optimizations for JavaScript/TypeScript tooling.

crates/oxc_diagnostics/README.md

@@ -0,0 +1,33 @@
+# Oxc Diagnostics
+
+Error reporting and diagnostic utilities for JavaScript and TypeScript tooling.
+
+## Overview
+
+This crate provides comprehensive error handling and diagnostic reporting capabilities. It implements the [miette] diagnostic trait, making it compatible with other Rust diagnostic tooling while providing specialized features for JavaScript/TypeScript errors.
+
+## Key Features
+
+- **Rich diagnostics**: Detailed error messages with source context
+- **Source highlighting**: Syntax-highlighted error locations
+- **Multiple error support**: Collect and report multiple errors at once
+- **Miette integration**: Compatible with the miette diagnostic ecosystem
+- **Severity levels**: Support for errors, warnings, and informational messages
+
+## Architecture
+
+### Diagnostic Components
+
+- **Message**: Primary error/warning description
+- **Labels**: Highlight specific source locations
+- **Help text**: Suggestions for fixing the issue
+- **Source context**: Display relevant source code sections
+
+### Error Flow
+
+1. **Creation**: Tools create `OxcDiagnostic` instances for problems
+2. **Collection**: `DiagnosticService` aggregates diagnostics
+3. **Formatting**: Rich terminal output with colors and context
+4. **Reporting**: Display to users in IDE, CLI, or other interfaces
+
+The diagnostic system ensures consistent, high-quality error reporting across all oxc tools.

crates/oxc_estree/README.md

@@ -0,0 +1,38 @@
+# Oxc ESTree
+
+ESTree compatibility layer for serialization and interoperability.
+
+## Overview
+
+This crate provides compatibility with the ESTree AST specification, primarily for serialization purposes. It enables oxc AST nodes to be serialized to and from JSON in ESTree format, facilitating interoperability with other JavaScript tools.
+
+## Key Features
+
+- **ESTree compatibility**: Convert oxc AST to/from standard ESTree format
+- **Serialization support**: JSON serialization/deserialization via serde
+- **Tool interoperability**: Enable integration with ESTree-based tools
+- **Optional feature**: Only enabled when `serialize` feature is active
+
+## Usage
+
+## Architecture
+
+### ESTree Specification
+
+ESTree is a community standard for representing JavaScript AST nodes. This crate ensures oxc's AST can be represented in this standard format while maintaining compatibility with the broader JavaScript tooling ecosystem.
+
+### Design Principles
+
+- **Compatibility**: Full compatibility with ESTree specification
+- **Optional overhead**: Only included when serialization is needed
+- **Type safety**: Maintains Rust's type safety during conversion
+- **Performance**: Efficient serialization with minimal overhead
+
+### Use Cases
+
+- **IDE integration**: Language servers communicating via JSON
+- **Tool interoperability**: Working with Babel, ESLint, and other ESTree tools
+- **Data exchange**: Transferring AST data between different systems
+- **Debugging**: Human-readable AST representation
+
+When the `serialize` feature is disabled, this crate provides only a placeholder trait to support derive macros without overhead.

crates/oxc_isolated_declarations/README.md

@@ -0,0 +1,40 @@
+# Oxc Isolated Declarations
+
+TypeScript isolated declarations transformer for generating `.d.ts` files.
+
+## Overview
+
+This crate implements TypeScript's isolated declarations feature, which generates TypeScript declaration files (`.d.ts`) from source code without requiring full type checking. This enables faster builds and better incremental compilation.
+
+## Key Features
+
+- **Fast declaration generation**: Generate `.d.ts` files without full type checking
+- **TypeScript 5.5+ compatibility**: Implements the latest isolated declarations specification
+- **Incremental builds**: Enables faster TypeScript compilation workflows
+- **Comprehensive support**: Handles classes, functions, interfaces, and complex types
+
+## Architecture
+
+### Isolated Declarations Concept
+
+Isolated declarations allow generating TypeScript declaration files without full type inference by requiring that:
+
+- All exported functions have explicit return types
+- All exported variables have explicit types
+- Type information is locally available
+
+### Implementation Details
+
+- **AST transformation**: Convert implementation AST to declaration AST
+- **Type extraction**: Extract and preserve type information
+- **Export analysis**: Determine what needs to be included in declarations
+- **Error reporting**: Provide helpful diagnostics for missing type annotations
+
+### Benefits
+
+- **Faster builds**: No full type checking required
+- **Incremental compilation**: Each file can be processed independently
+- **Parallel processing**: Multiple files can be processed simultaneously
+- **Simplified tooling**: Easier to integrate into build systems
+
+This implementation follows the TypeScript compiler's approach while leveraging oxc's performance-oriented architecture.

crates/oxc_linter/README.md

@@ -0,0 +1,40 @@
+# Oxc Linter
+
+High-performance ESLint-compatible linter for JavaScript and TypeScript.
+
+## Overview
+
+This crate provides a fast, ESLint-compatible linting engine with comprehensive rule support. It leverages oxc's high-performance AST and semantic analysis to deliver significantly faster linting than traditional tools.
+
+## Key Features
+
+- **ESLint compatibility**: Drop-in replacement for most ESLint workflows
+- **High performance**: 50-100x faster than ESLint on large codebases
+- **Comprehensive rules**: Supports most popular ESLint rules and plugins
+- **TypeScript support**: Full TypeScript linting with type-aware rules
+- **Plugin system**: Extensible architecture for custom rules
+
+## Architecture
+
+### Rule System
+
+- **Rule categories**: Correctness, Suspicious, Pedantic, Style, etc.
+- **Configurable severity**: Error, Warning, or Off for each rule
+- **Auto-fixing**: Many rules can automatically fix issues
+- **Plugin support**: Load external rule collections
+
+### Performance Design
+
+- **Single AST pass**: Most rules run in a single traversal
+- **Efficient analysis**: Leverages oxc's semantic analysis
+- **Parallel execution**: Process multiple files concurrently
+- **Memory efficiency**: Uses arena allocation for optimal performance
+
+### ESLint Compatibility
+
+- **Configuration format**: Supports ESLint config files
+- **Rule parity**: Implements behavior-compatible versions of popular rules
+- **Plugin ecosystem**: Compatible with many ESLint plugins
+- **Migration path**: Easy transition from ESLint to oxlint
+
+The linter is designed to be both a standalone tool and a library component for integration into other development tools.