Skip to content

AGENTS.md

Latest commit

 

History

History
84 lines (61 loc) · 3.16 KB

AGENTS.md

File metadata and controls

84 lines (61 loc) · 3.16 KB

AGENTS.md

Instructions for AI coding agents working on torrust-linting.

Project overview

torrust-linting is a Rust library and CLI binary that runs all standard Torrust project linters in one command. It wraps external tools (markdownlint, yamllint, taplo, cspell, shellcheck) and Rust built-ins (clippy, rustfmt) behind a unified interface.

  • Crate type: hybrid — library (torrust_linting) + binary (linter)
  • Rust edition: 2021, rust-version = "1.85"
  • License: MIT

Build commands

cargo build                        # Build library + binary
cargo build --bin linter           # Build only the CLI binary
cargo build --release              # Release build

Run the linter

cargo run                          # Run all linters (default)
cargo run -- all                   # Explicit "all"
cargo run -- markdown              # Single linter
cargo run -- yaml
cargo run -- toml
cargo run -- cspell
cargo run -- clippy
cargo run -- rustfmt
cargo run -- shellcheck

After a build you can also run the binary directly:

./target/debug/linter all

Testing

There are no unit tests at the moment. The primary verification is running the linter against itself:

cargo run   # Must exit 0 — this is the CI gate

This is mandatory before every commit. The CI workflow (.github/workflows/linting.yml) runs the exact same command and will reject any PR that does not pass. Do not open a PR without confirming exit code 0 locally first.

Code style

  • Format with cargo fmt before committing. The project uses a custom rustfmt.toml (group_imports = "StdExternalCrate", max_width = 130).
  • No clippy warnings allowed (cargo clippy -- -D warnings).
  • TOML files must pass taplo fmt --check **/*.toml. Auto-fix with taplo fmt **/*.toml.
  • Markdown files must pass markdownlint.
  • YAML files must pass yamllint -c .yamllint-ci.yml.
  • Spell-check all files with cspell. Add new technical terms to project-words.txt (one word per line, alphabetical order).

Adding a new linter

  1. Create src/linters/<name>.rs with a public run_<name>_linter() -> Result<()> function.
  2. Register it in src/linters/mod.rs (pub mod <name>; pub use <name>::run_<name>_linter;).
  3. Re-export from src/lib.rs.
  4. Add a Commands variant in src/cli.rs and handle it in execute_command().
  5. Add the call to run_all_linters() in src/cli.rs.

Configuration files

Place these in the project root when using this linter on another repo:

File Used by
.markdownlint.json markdownlint
.yamllint-ci.yml yamllint
.taplo.toml taplo
cspell.json cspell

PR instructions

  • Run cargo run and confirm exit code 0 before every commit and before opening a PR. PRs that fail the linting CI will be rejected.
  • Branch naming: feat/<short-description>, fix/<short-description>, chore/<short-description>.
  • Commit messages follow Conventional Commits: feat:, fix:, chore:, docs:, refactor:.
  • Keep Cargo.lock committed (the crate ships a binary).