AGENTS.md git:20261104.1e26e80A

Immutable. This exact content never changes and is served at /api/v1/blob/376aadcd6ec0584a.

# AGENTS.md

`easement` is a Rust command line: an architecture quality gate. Go, TypeScript, Python, Rust, PHP, Java, C# and Ruby dependencies come from SCIP indexers that `src/indexer.rs` runs and `src/scip.rs` reads; Kotlin and Swift still use tree-sitter adapters (`src/lang/`) that extract and resolve imports. What easement knows of each language (extensions, test files, standard library, manifest, whether `unused` judges it) is one entry in `src/lang/registry.rs`; rules ask it, never an extension. The tests need `scip-go`, `scip-typescript`, `scip-python`, `rust-analyzer`, `scip-java` and a JDK with Maven, which `mise.toml` installs, and `scip-php` with `composer`, `scip-dotnet` with `dotnet` and `scip-ruby` (see the CI workflow). The core (`src/config.rs`, `src/components.rs`, `src/check.rs`, `src/baseline.rs`, `src/diff.rs`) is language-agnostic.

- Tools come from `mise.toml`. `mise run check` runs every lint (the same set CI runs), easement on its own code (`easement.yml`: a new module is placed there) included, and `cargo test` runs the tests; both must pass before a push. `mise run setup` installs the git hooks and the agent skills (`mise run skills` alone reinstalls them); `mise run update` bumps the npm, Cargo and skills dependencies and `mise run upgrade` the mise tools.
- A language is added in one shape: its entry in `src/lang/registry.rs`, its `Indexer` in `src/indexer.rs` (or a tree-sitter adapter in `src/lang/`), and its symbol scheme normalized in `src/scip.rs` while the index is read. Past that point every language looks the same: the same `Reference`, `Dep` and `Violation`, the same cache and the same partial-analysis fields, so code outside the registry, the indexers and the adapters names no language. A language that does not fit this shape needs a general mechanism that serves every language, agreed in an issue first.
- A rule is defined once for every language: one rule id, one config key, judged on the index, with the registry supplying what differs by language. A new rule, rule kind or config key starts as an issue that settles that shape; the pull request follows it.
- One pull request carries one change: a new language and new rules go in separate pull requests.
- A change in behaviour starts with a test: unit tests next to the code, end-to-end tests in `tests/cli.rs` against the fixture projects in `tests/fixtures/`. The output agents read is pinned by snapshots in `tests/snapshots/`: a change to it fails the test with a `.snap.new` next to the snapshot; check it with `cargo insta review` and accept it only when the change is meant.
- Never disable a lint rule or add an ignore to get a change through. An exception is narrow (one path, one rule), carries a reason and needs a human decision.
- `.github/workflows/release.yml` is generated by `dist` from `dist-workspace.toml`: run `dist generate` after changing the config, never edit the workflow by hand.
- Releases are made by merging the pull request that release-please opens from the Conventional Commits on `main`. It bumps the version and `CHANGELOG.md`; the tag starts `release.yml`, which builds the archives and publishes the GitHub release, the Homebrew formula (`publish-homebrew.yml`, `RELEASE_PLEASE_TOKEN` must reach `mokevnin/homebrew-tap`) and the crate (`publish-crates.yml`, `CARGO_REGISTRY_TOKEN`). Never bump the version or tag by hand.
- The main callers are coding agents, not people. Output says what not to trust: a clean verdict over partly indexed code (uncovered files), a cached result or an unreliable `suggest` is flagged in a structured field (`--format json`) and in the text, with the reason and how to re-verify (for example `--no-cache`). A cache hit needs a conservative key: when in doubt, miss.
- The main checkout always stays on `main`: never switch it to another branch. A worktree may have its own branch; its commits land on `main`.
- Commit messages follow Conventional Commits (commitlint checks them). Text in this repository is English.