11# AGENTS.md - AI Assistant Guide for Oxc
22
33Oxc is a high-performance JavaScript/TypeScript toolchain written in Rust containing:
4+
45- Parser (JS/TS with AST), Linter (oxlint), Formatter, Transformer, Minifier
56
67## Repository Structure
78
89Rust workspace with key directories:
10+
911- ` crates/ ` - Core functionality (start here when exploring)
1012- ` apps/ ` - Application binaries (oxlint)
1113- ` napi/ ` - Node.js bindings
@@ -16,8 +18,9 @@ Rust workspace with key directories:
1618Avoid editing ` generated ` subdirectories.
1719
1820### Core Crates
21+
1922- ` oxc_parser ` - JS/TS parser
20- - ` oxc_ast ` - AST definitions/utilities
23+ - ` oxc_ast ` - AST definitions/utilities
2124- ` oxc_linter ` - Linting engine/rules
2225- ` oxc_semantic ` - Semantic analysis/symbols
2326- ` oxc_transformer ` - Code transformation
@@ -32,11 +35,13 @@ Avoid editing `generated` subdirectories.
3235Prerequisites: Rust (MSRV: 1.87.0), Node.js, pnpm, just
3336
3437** Setup Notes:**
38+
3539- ` just init ` has already been run, all tools (` cargo-insta ` , ` typos-cli ` , ` cargo-shear ` , ` dprint ` ) are already installed, do not run ` just init ` .
3640- Rust and ` cargo ` components ` clippy ` , ` rust-docs ` and ` rustfmt ` has already been installed, do not install them.
3741- Always run ` just ready ` as the last step after code has been committed to the repository.
3842
3943Key commands (tools already installed):
44+
4045``` bash
4146just ready # Run all checks (use after commits)
4247just fmt # Format code (run after modifications)
@@ -53,26 +58,30 @@ pnpm test # Node.js tests
5358## Examples
5459
5560Most crates have examples in their ` examples/ ` directories:
61+
5662``` bash
5763cargo run -p < crate_name> --example < example_name> [filename]
5864```
5965
6066Key examples:
67+
6168- ` oxc_parser --example parser ` - Basic parsing/AST
62- - ` oxc_linter --example linter ` - Linting demo
69+ - ` oxc_linter --example linter ` - Linting demo
6370- ` oxc_semantic --example semantic ` - Semantic analysis
6471- ` oxc_transformer --example transformer ` - Code transformation
6572- ` oxc --example compiler --features="full" ` - Full pipeline
6673
6774## Code Navigation
6875
6976### Key Locations
77+
7078- AST: Start with ` oxc_ast ` , use ` oxc_ast_visit ` for traversal
7179- Linting rules: ` crates/oxc_linter/src/rules/ ` (visitor pattern)
7280- Parser: ` crates/oxc_parser/src/lib.rs ` , lexer in ` src/lexer/ `
7381- Tests: Co-located with source, integration in ` tests/ ` , uses ` insta ` for snapshots
7482
7583### Conventions
84+
7685- Use ` oxc_allocator ` for memory management
7786- Follow rustfmt config in ` .rustfmt.toml `
7887- Use ` oxc_diagnostics ` for errors with source locations
@@ -81,28 +90,33 @@ Key examples:
8190## Common Tasks
8291
8392### Adding Linting Rule
93+
84941 . Create module in ` crates/oxc_linter/src/rules/ `
85952 . Implement using visitor pattern
86963 . Add tests in same module
87974 . Register in appropriate category
8898
8999### Parser Changes
100+
901011 . Research and test grammar changes thoroughly
911022 . Update AST definitions in ` oxc_ast ` if needed
921033 . Ensure existing tests pass
931044 . Add tests for new features
94105
95106### Working with Transformations
107+
961081 . Understand AST structure first
971092 . Use visitor pattern for traversal
981103 . Handle node ownership/allocator carefully
991114 . Test with various input patterns
100112
101113## Notes
114+
102115- Rapidly evolving project - APIs may change
103116- Performance is critical for all changes
104117- Maintain JS/TS standard compatibility
105118- Breaking changes need documentation and discussion
106119
107120---
121+
108122For human contributors see ` CONTRIBUTING.md ` and [ oxc.rs] ( https://oxc.rs )
0 commit comments