Unnamed repository; edit this file 'description' to name the repository.
Merge pull request #22856 from Veykril/lukaswirth/push-kzkzsunnostv
Improve AGENTS.md
| -rw-r--r-- | CLAUDE.md | 78 |
1 files changed, 49 insertions, 29 deletions
@@ -1,40 +1,60 @@ -**Reminder: All AI usage must be disclosed in commit messages, see -CONTRIBUTING.md for more details.** +## AI Policy -## Build Commands +Follow `AI_POLICY.md`. In particular: -```bash -cargo build # Build all crates -cargo test # Run all tests -cargo test -p <crate> # Run tests for a specific crate (e.g., cargo test -p hir-ty) -cargo lint # Run clippy on all targets -cargo xtask codegen # Run code generation -cargo xtask tidy # Run tidy checks -UPDATE_EXPECT=1 cargo test # Update test expectations (snapshot tests) -RUN_SLOW_TESTS=1 cargo test # Run heavy/slow tests -``` +- Do not use AI to author issue/PR comments or replies to maintainers. +- Do not autonomously open issues or pull requests. +- Do not author code for issues labeled both `E-easy` and `E-has-instructions`. +- The human contributor must understand the changes and disclose AI use as required by the policy. -## Key Architectural Invariants -- Typing in a function body never invalidates global derived data -- Parser/syntax tree is built per-file to enable parallel parsing -- The server is stateless (HTTP-like); context must be re-created from request parameters -- Cancellation uses salsa's cancellation mechanism; computations panic with a `Cancelled` payload +## Repository Guides -### Code Generation +- Architecture and crate ownership: `docs/book/src/contributing/architecture.md` +- Rust style: `docs/book/src/contributing/style.md` +- Testing conventions and fixture syntax: `docs/book/src/contributing/testing.md` +- Contributor workflows: `docs/book/src/contributing/README.md` +- AI restrictions: `AI_POLICY.md` -Generated code is committed to the repo. Grammar and AST are generated from `ungrammar`. Run `cargo test -p xtask` after adding inline parser tests (`// test test_name` comments). +Read the relevant sections before making architectural, generated-code, protocol, or test-harness changes. + +## Change Workflow + +- Find the nearest existing implementation and its tests before adding new code. +- Extend existing helpers and test harnesses instead of creating parallel abstractions. +- Keep changes focused and prefer the smallest change that fits the existing design. +- When fixing a bug, add the smallest fixture that reproduces it and test the behavior through the existing interface. + +## Scope and Dependencies + +- Treat new `pub` items, public re-exports, and Cargo dependencies as architectural changes, not routine implementation details. +- Prefer keeping functionality inside the crate that owns the relevant data. +- Be conservative with crates.io dependencies. Reuse existing dependencies or `stdx`; do not add small helper crates without strong justification. + +## Key Invariants + +- User-provided Rust code, malformed syntax, broken builds, and proc-macro failures must not cause ordinary IDE features to panic. +- Assert invariants liberally. For impossible conditions from which the server can recover, prefer `stdx::never!` or `stdx::always!` and return a safe fallback instead of panicking. ## Testing -Tests are snapshot-based using `expect-test`. Test fixtures use a mini-language: -- `$0` marks cursor position -- `// ^^^^` labels attach to the line above -- `//- minicore: sized, fn` includes parts of minicore (minimal core library) -- `//- /path/to/file.rs crate:name deps:dep1,dep2` declares files/crates +- Many feature tests use Rust-code fixtures and `expect-test` snapshots. Follow the nearest existing test helper and fixture convention rather than introducing a new test harness. +- Before planning or writing fixture-based tests, review `docs/book/src/contributing/testing.md` for fixture annotations, `minicore`, and multi-file/multi-crate syntax. +- Keep Rust fixtures minimal; remove syntax unrelated to the behavior under test. +- Use unindented multiline raw strings, matching nearby tests. +- For regressions, first reproduce the failure with a focused test, then implement the fix. + +## Generated Code + +- Generated files are committed. Edit the generator rather than generated output. +- Run `cargo xtask codegen` after changing grammar, generated AST definitions, configuration schemas, or other codegen inputs. +- After adding parser inline tests (`// test name`), run `cargo test -p xtask`, update the relevant expectations, and inspect the generated diff. -## Style Notes +## Validation -- Use `stdx::never!` and `stdx::always!` instead of `assert!` for recoverable invariants -- Use `T![fn]` macro instead of `SyntaxKind::FN_KW` -- Use keyword name mangling over underscore prefixing for identifiers: `crate` → `krate`, `fn` → `func`, `struct` → `strukt`, `type` → `ty` +- Start with the narrowest relevant test: `cargo test -p <crate> <test-name>` or `cargo test -p <crate>`. +- After Rust changes, run the affected crate's tests and `cargo clippy -p <crate> --all-targets -- --cap-lints warn`; broaden validation when the change crosses crates. +- Use `cargo lint` to run Clippy on all workspace targets. +- Run `cargo xtask tidy` for repository-wide structural or generated-code changes. +- When updating snapshots with `UPDATE_EXPECT=1`, inspect the expectation diff rather than accepting it blindly. +- Use `RUN_SLOW_TESTS=1 cargo test` when the affected area has slow tests. |