blockwatch CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project

BlockWatch is a language-agnostic linter (Rust CLI, published on crates.io) that enforces rules declared inside HTML-like <block ...> tags found in source-file comments. It can run across the whole tree or only on the changed lines of a piped git diff --patch.

Common commands

cargo build                                # build CLI
cargo run -- [args]                        # run locally
cargo test                                 # run all unit + integration tests
cargo test --test keep_sorted              # run one integration test file (tests/<name>.rs)
cargo test <pattern>                       # run tests whose name matches
cargo test -- --nocapture                  # show stdout/stderr from tests
cargo fmt                                  # format
cargo clippy --all-targets -- -D warnings  # lint

Fuzzing (nightly toolchain + cargo-afl required) lives in fuzz/; see fuzz/README.md.

Integration tests use assert_cmd to invoke the compiled binary against fixtures in tests/testdata/. Many of them also pipe synthetic diffs into stdin — when adding a test, mirror the existing pattern in tests/<validator>.rs.

Agentic coding rules

Strict adherence to the following rules is absolutely required when working with this project:

1. Always use the rust-analyzer and rustrover MCP tool to navigate the Rust codebase both for reads and writes.
2. Never use one-off scripts where the rust-analyzer or rustrover MCP tool could do the job.
3. Prefer native code editing mechanism or MCP tools over one-off scripts.
4. Never commit anything automatically. All modified code must be reviewed by a human.
5. Always escalate to a human when there is any ambiguity or UX/security/performance concerns. Provide clear context and options to a human to make a decision.
6. Never go down a rabbit hole in order to circumvent blockers. If the solution appears too complicated - escalate to a human immediately.
7. Always use clear, easy to follow human-readable language when writing any sort of comments or prose.
8. Never narrate what the code is doing when writing comments, instead explain why the code is written in a specific way. If the solution is too exotic - escalate to a human.
9. Never make the comments look relevant to just the current task. They should be clear in the future to any developer unfamiliar with the specific current task and even with the project itself.