Skip to content

Commit d6d6a93

Browse files
CopilotCopilot
authored
chore(ai): Add AGENTS.md and GitHub Copilot setup workflow (#628)
1 parent 7e8645e commit d6d6a93

File tree

2 files changed

+232
-0
lines changed

2 files changed

+232
-0
lines changed

‎.github/workflows/copilot-setup-steps.yml

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
name: Copilot Setup Steps
2+
3+
# This workflow defines the setup steps that GitHub Copilot agents will use
4+
# to prepare the development environment for the oxc project.
5+
# It preinstalls tools and dependencies needed for Rust and Node.js development.
6+
7+
on:
8+
workflow_dispatch:
9+
pull_request:
10+
types: [opened, synchronize]
11+
paths:
12+
- .github/workflows/copilot-setup-steps.yml
13+
push:
14+
branches:
15+
- main
16+
paths:
17+
- .github/workflows/copilot-setup-steps.yml
18+
19+
permissions: {}
20+
21+
jobs:
22+
copilot-setup-steps:
23+
name: Setup Development Environment for Copilot
24+
runs-on: ubuntu-latest
25+
steps:
26+
# Checkout full repo for git history.
27+
- uses: actions/checkout@v4
28+
with:
29+
persist-credentials: false
30+
31+
- uses: oxc-project/setup-rust@cd82e1efec7fef815e2c23d296756f31c7cdc03d # v1.0.0
32+
with:
33+
cache-key: warm
34+
save-cache: false
35+
tools: just,watchexec-cli,cargo-insta,typos-cli,cargo-shear,dprint
36+
components: clippy rust-docs rustfmt
37+
38+
- uses: oxc-project/setup-node@f42e3bda950c7454575e78ee4eaac880a077700c # v1.0.0
39+
40+
- uses: ./.github/actions/pnpm
41+
42+
- name: Restore dprint plugin cache
43+
id: cache-restore
44+
uses: actions/cache/restore@5a3ec84eff668545956fd18022155c47e93e2684 # v4.2.3
45+
with:
46+
key: dprint-${{ hashFiles('dprint.json') }}
47+
path: ~/.cache/dprint

‎AGENTS.md

Lines changed: 185 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,185 @@
1+
# AI Agent Guidelines for oxc-resolver
2+
3+
This document provides guidance for AI coding assistants (like GitHub Copilot, Cursor, Claude, etc.) when working with the oxc-resolver codebase.
4+
5+
## Project Overview
6+
7+
oxc-resolver is a Rust port of webpack's enhanced-resolve, providing ESM and CommonJS module resolution. It offers both a Rust crate and Node.js bindings via NAPI.
8+
9+
### Key Technologies
10+
11+
- **Rust**: Core implementation using Rust 2024 edition (MSRV: 1.85.0)
12+
- **NAPI**: Node.js bindings for JavaScript/TypeScript usage
13+
- **WebAssembly**: Browser support
14+
- **GitHub Actions**: CI/CD workflows
15+
16+
## Architecture
17+
18+
```
19+
oxc-resolver/
20+
├── src/ # Core Rust implementation
21+
├── napi/ # Node.js NAPI bindings
22+
├── tests/ # Test fixtures and data
23+
├── examples/ # Usage examples
24+
├── benches/ # Performance benchmarks
25+
└── .github/ # GitHub workflows and configs
26+
```
27+
28+
## Development Workflow
29+
30+
`just init` has already been run, all tools (`typos-cli`, `cargo-shear`, `dprint`) are already installed, do not run `just init`.
31+
32+
Rust and `cargo` components `clippy`, `rust-docs` and `rustfmt` has already been installed, do not install them.
33+
34+
Always run `just ready` as the last step after code has been committed to the repository.
35+
36+
### Common Tasks
37+
38+
```bash
39+
just ready # Run all checks (format, lint, test, build)
40+
just test # Run all tests (Rust + Node.js)
41+
just check # Cargo check with all features
42+
just lint # Run clippy with strict settings
43+
just fmt # Format code (cargo fmt + dprint)
44+
```
45+
46+
## Code Conventions
47+
48+
### Rust
49+
50+
- Use Rust 2024 edition features
51+
- Follow standard Rust formatting (`cargo fmt`)
52+
- All clippy warnings must be addressed (`cargo clippy -- --deny warnings`)
53+
- Use `tracing` for logging/instrumentation
54+
- Implement `FileSystem` trait for custom file systems
55+
56+
### Node.js/TypeScript
57+
58+
- Use TypeScript for type definitions (`index.d.ts`)
59+
- Follow existing API patterns in NAPI bindings
60+
- Use vitest for testing
61+
- Support both ESM and CommonJS usage
62+
63+
### Documentation
64+
65+
- Use rustdoc for Rust APIs
66+
- Maintain TypeScript definitions for Node.js API
67+
- Update README.md for significant changes
68+
- Add examples for new features
69+
70+
## Key APIs
71+
72+
### Rust
73+
74+
```rust
75+
use oxc_resolver::{ResolveOptions, Resolver};
76+
77+
let options = ResolveOptions::default();
78+
let resolver = Resolver::new(options);
79+
let resolution = resolver.resolve("/path/to/project", "./module");
80+
```
81+
82+
### Node.js
83+
84+
```javascript
85+
import resolve, { ResolverFactory } from 'oxc-resolver';
86+
87+
// Simple resolve
88+
const result = resolve.sync(process.cwd(), './module');
89+
90+
// Advanced usage
91+
const resolver = new ResolverFactory({
92+
conditionNames: ['node', 'import'],
93+
extensions: ['.js', '.ts', '.json'],
94+
});
95+
```
96+
97+
## Testing Strategy
98+
99+
### Test Categories
100+
101+
1. **Enhanced-resolve compatibility**: Tests ported from webpack/enhanced-resolve
102+
2. **TypeScript support**: tsconfig-paths functionality
103+
3. **Yarn PnP**: Plug'n'Play resolution
104+
4. **Node.js compatibility**: ESM/CJS resolution behavior
105+
5. **Performance**: Benchmarks against enhanced-resolve
106+
107+
### Adding Tests
108+
109+
- Add Rust tests in `src/tests/`
110+
- Add Node.js tests in `napi/`
111+
- Use existing fixtures in `tests/` directory
112+
- Ensure tests work on Windows, macOS, and Linux
113+
114+
## Common Patterns
115+
116+
### Error Handling
117+
118+
```rust
119+
// Use proper error types
120+
use oxc_resolver::{ResolveError, ResolveErrorKind};
121+
122+
match resolver.resolve(path, specifier) {
123+
Ok(resolution) => { /* handle success */ },
124+
Err(ResolveError { kind: ResolveErrorKind::NotFound, .. }) => { /* handle not found */ },
125+
Err(err) => { /* handle other errors */ }
126+
}
127+
```
128+
129+
### Configuration
130+
131+
```rust
132+
// Build options incrementally
133+
let options = ResolveOptions {
134+
condition_names: vec!["node".to_string(), "import".to_string()],
135+
extensions: vec![".js".to_string(), ".ts".to_string()],
136+
main_fields: vec!["module".to_string(), "main".to_string()],
137+
..Default::default()
138+
};
139+
```
140+
141+
## Performance Considerations
142+
143+
- Use `FileSystem` trait for custom file systems (including in-memory)
144+
- Cache `Resolver` instances when possible
145+
- Consider `fullySpecified: true` for better performance when extensions are known
146+
- Profile with `cargo bench` for performance-critical changes
147+
148+
## Debugging
149+
150+
### Rust
151+
152+
```bash
153+
# Enable tracing
154+
RUST_LOG=oxc_resolver=debug cargo test
155+
```
156+
157+
### Node.js
158+
159+
```bash
160+
# Enable tracing
161+
OXC_LOG=DEBUG node your_program.js
162+
```
163+
164+
## Contributing Guidelines
165+
166+
1. **Small, focused changes**: Make minimal modifications
167+
2. **Test coverage**: Add tests for new functionality
168+
3. **Documentation**: Update docs for API changes
169+
4. **Performance**: Run benchmarks for core changes
170+
5. **Compatibility**: Maintain enhanced-resolve compatibility where possible
171+
172+
## AI Assistant Tips
173+
174+
- **Context awareness**: This is a low-level resolver, performance matters
175+
- **Test compatibility**: Changes should not break existing enhanced-resolve compatibility
176+
- **Cross-platform**: Consider Windows path handling differences
177+
- **Memory usage**: Be mindful of allocations in hot paths
178+
- **Error messages**: Provide helpful error messages that match Node.js behavior
179+
180+
## References
181+
182+
- [Enhanced Resolve](https://github.com/webpack/enhanced-resolve) - Original implementation
183+
- [Node.js Module Resolution](https://nodejs.org/api/modules.html) - CommonJS algorithm
184+
- [Node.js ESM Resolution](https://nodejs.org/api/esm.html#resolution-algorithm) - ESM algorithm
185+
- [TypeScript Module Resolution](https://www.typescriptlang.org/docs/handbook/module-resolution.html)

0 commit comments

Comments
 (0)