rclean-cli 0.2.0

Find and safely clean rebuildable developer artifacts across local workspaces
# Contributing to rclean

Thanks for taking the time to contribute. `rclean` is a small CLI with
a deliberately narrow scope — these notes capture the working patterns
so a PR can land cleanly the first time.

## Scope and product trust model

`rclean` deletes files. The trust model **is** the product:

- `scan` never deletes.
- `clean --all` selects only `safe` candidates unless `--include-caution`
  is passed. **Blocked candidates are never selected**, even with
  `--include-blocked`.
- Plan-based cleanup re-validates every path against the live filesystem
  before deleting, refuses to follow new symlinks, and rejects plans
  whose roots have changed shape since the scan.

A change that weakens any of these guarantees needs an explicit
discussion in the PR before code, ideally as a SPEC update under
`docs/specs/` first. See [`SECURITY.md`](SECURITY.md) for the threat
model and reporting workflow.

## Toolchain

- **Edition**: Rust 2024.
- **MSRV**: `rust-version = "1.95"` in `Cargo.toml`. CI verifies the
  pinned MSRV on Ubuntu; PRs that need a newer toolchain must bump
  `rust-version` and explain why in the commit message.
- **OS coverage**: CI runs `fmt`, `clippy`, `test`, and a release build
  on Ubuntu, macOS, and Windows. Platform-specific code must be gated
  with `cfg(unix)` / `cfg(windows)` and have at least one
  platform-gated test in `tests/cross_platform.rs`.

## Local verification

Run these before opening a PR — they mirror what CI runs:

```bash
cargo fmt -- --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test
cargo build --release
rustup run 1.95 cargo build --all-targets --all-features
rustup run 1.95 cargo test
```

If your change is performance-sensitive, also run the benchmark suite
(see `benches/` and `docs/perf/`) and include the before/after numbers
in the PR body.

## Agent-assisted workflow

AI agents should start with [`AGENTS.md`](AGENTS.md). Small docs-only
changes can be handled directly with focused verification. Substantial
rule, safety, CLI, or multi-module changes need a linked GitHub issue
and, when behavior is ambiguous or risky, a SpecRail packet under
`specs/GH<number>/`.

## PR shape

- Use the repository PR template and fill in the safety/scope and
  verification sections. If a checklist item is not applicable, say why
  in the PR body instead of deleting it.
- **Small and focused.** One concern per PR. If a refactor and a fix
  are tangled, land the refactor first as a pure-rename PR, then the
  fix.
- **Conventional commits.** Existing history uses `feat:`, `fix:`,
  `perf:`, `refactor:`, `test:`, `docs:`, `chore:` prefixes with an
  optional scope (e.g. `perf(scan): ...`).
- **Sign-off.** Commits should include a `Signed-off-by:` trailer
  (`git commit -s`). The Lore convention also encourages capturing
  *why* the change exists, not just *what* changed.
- **No bundled fixes.** Don't roll style edits into behavior changes.
  Style-only changes are their own commit and PR.

## Code conventions

- **File size**: single-file limit is 800 lines (hard ceiling). When
  a module approaches that, split it into a directory module —
  `src/rules/` is the existing example. The split should be a separate
  pure-rename PR before any feature work lands on top.
- **No silent degradation.** Errors that cause user-visible wrong
  output must be raised, not logged at `warning` and replaced with a
  fallback. Optional features that can degrade safely (e.g. cache
  write failure) are the exception and must mark the degraded path
  explicitly.
- **No new aliases.** When renaming a function, type, or flag, remove
  every old reference in the same change — don't leave deprecated
  aliases.
- **Tests with every fix.** Every bug fix must add a regression test
  that fails before the fix and passes after. Refactors must keep
  existing tests green.
- **Symlink behavior** is part of the contract: symlinked candidates
  resolve to `Safety::Blocked` in both `scan` and `explain`. Anything
  touching the walker or `apply_path_safety` needs an explicit
  symlink case in tests.

## Adding a new ecosystem rule

Built-in rules live in `src/rules/`, one file per ecosystem. The
contract is `classify_candidate(parent, name, path) -> Option<CandidateDraft>`:

1. Pick the right file (`src/rules/node.rs`, `python.rs`, ...). If
   the ecosystem is new, add a sibling file and register it in
   `src/rules/mod.rs` and `src/rules/catalog.rs`.
2. Add at least one positive test in `tests/rules.rs` and one negative
   test that confirms the rule does *not* fire without its marker.
3. Generic directory names (`build`, `dist`, `out`, `target`,
   `vendor`) require a project marker — never classify them by name
   alone.
4. Update the **Supported Ecosystems** table in `README.md`.

User-extensible rules live in `.rclean.toml` (per scan root). User
rules layer *after* built-in rules and cannot produce `Safety::Blocked`.
The file format is documented in the README.

## Reporting bugs

- Functional bugs (wrong candidate, wrong size, wrong category):
  open a
  [scan false positive report]https://github.com/majiayu000/rclean/issues/new?template=scan-false-positive.yml
  with a minimal reproducible directory layout (`mkdir -p` script is
  ideal).
- Cleanup behavior that looks risky or surprising: open a
  [cleanup safety concern]https://github.com/majiayu000/rclean/issues/new?template=cleanup-safety-concern.yml
  with the command, safety tier, and sanitized output.
- New ecosystem rules, install/package requests, output modes, and
  documentation gaps: open a
  [feature request]https://github.com/majiayu000/rclean/issues/new?template=feature-request.yml.
- Security or trust-model issues: follow the private disclosure
  process in [`SECURITY.md`]SECURITY.md — do not file a public issue.

## Release process

Versioning is `0.1.x` for the v0.1 series; behavior-breaking changes
require either a minor bump (post-1.0) or an explicit migration note
in `CHANGELOG.md`. The roadmap for the current minor series lives in
`docs/specs/v0.1.x-roadmap.md`.