336b42c277
Some checks failed
ci / fast (linux) (push) Failing after 1m41s
Address 11 code review findings: fix DOM-mode vacuous error pass, add source locations to ReferenceError/TypeError, fix progress counter overcounting, harden promise registry with overflow guards, and clean up misleading test assertions. Add 16 new tests covering the fixes. Create Test262 roadmap documenting the feature gap for real conformance testing. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
69 lines
3.1 KiB
Markdown
69 lines
3.1 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Build & Test Commands
|
|
|
|
```bash
|
|
just ci # Full validation: fmt, lint, test, policy, metrics
|
|
just test # Run tests only (cargo xtest)
|
|
just lint # Run clippy (cargo xclippy -- -D warnings)
|
|
just fmt # Check formatting (cargo fmt --all --check)
|
|
just fix # Auto-fix formatting (cargo fmt --all)
|
|
just policy # Run safety checks (unsafe, deps, file sizes)
|
|
just san # Run sanitizers (Linux nightly only)
|
|
```
|
|
|
|
Integration tests in `tests/` require `[[test]]` entries in root Cargo.toml.
|
|
|
|
## Architecture
|
|
|
|
### Crate Layers (enforced by `scripts/check_deps.sh`)
|
|
|
|
- **Layer 0**: `shared` - Common types, geometry, errors
|
|
- **Layer 1**: Engine crates - No upward dependencies allowed
|
|
- JS: `js`, `js_vm`, `js_parser`
|
|
- Rendering: `html`, `dom`, `css`, `selectors`, `style`, `layout`, `display_list`, `render`
|
|
- Infrastructure: `net`, `storage`, `image`, `fonts`, `graphics`, `platform`, `web_api`
|
|
- **Layer 2**: `browser_runtime` - Tabs, navigation, history
|
|
- **Layer 3**: `app_browser` - Window, event loop, application entry
|
|
|
|
### Rendering Pipeline
|
|
|
|
```
|
|
HTML Parse → DOM Tree → CSS Parse → Style Computation → Layout → Display List → Render
|
|
```
|
|
|
|
Each phase produces stable representations. Uses arena-based storage with IDs (`NodeId`, `StyleId`, `LayoutId`) instead of lifetimes for cross-crate APIs.
|
|
|
|
### Threading Model
|
|
|
|
Single-threaded main thread (JS, DOM, style, layout, paint). Worker threads for network I/O and image decoding only.
|
|
|
|
## Critical Rules
|
|
|
|
1. **No unsafe code** except in `crates/platform/` and `crates/graphics/`
|
|
2. **No upward dependencies** between layers
|
|
3. **Every bug fix requires a regression test**
|
|
4. **New dependencies require rationale in PR**
|
|
5. **Run `just ci` after every code change**
|
|
|
|
## Testing
|
|
|
|
- **Unit tests**: Inline `#[cfg(test)] mod tests` in crate source files, broken into multiple files when they get large
|
|
- **Integration tests**: `tests/*.rs` - each needs `[[test]]` in root Cargo.toml
|
|
- **Golden tests**: `tests/goldens.rs` - compares layout tree and display list dumps against expected outputs in `tests/goldens/expected/`
|
|
- **JS262 conformance**: `tests/js262_harness.rs` - Test262-inspired suite with TOML manifest at `tests/external/js262/js262_manifest.toml`
|
|
- Run suite: `cargo test -p rust_browser --test js262_harness js262_suite_matches_manifest_expectations -- --nocapture`
|
|
- Manage status: `just js262-status promote --id <test-id>` (promote known_fail to pass)
|
|
|
|
## Key Documentation
|
|
|
|
- `docs/browser_architecture_initial_exploration.md` - Design principles, threading model
|
|
- `docs/browser_project_structure_modularization_guide.md` - Crate layout, dependency rules
|
|
- `docs/browser_testing_strategy_high_level_to_detailed.md` - Testing approach
|
|
- `docs/js_feature_matrix.md` - JS feature support status and test counts
|
|
- `docs/js_conformance_report.md` - JS262 conformance test results by feature area
|
|
- `docs/test262_roadmap.md` - Gap analysis and implementation plan for real Test262 support
|
|
- `AGENTS.md` - Agent contract and rules
|