tarn: Instructions file for Claude Code

CLAUDE.md

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

Project Overview

Tarn is a CLI-first API testing tool written in Rust. Tests are defined in .tarn.yaml files. Designed for AI-assisted workflows: an LLM writes tests, runs tarn run, parses structured JSON output, and iterates.

Build & Run Commands

cargo build                    # dev build
cargo build --release          # release build (single binary, zero runtime deps)
cargo run -- run               # run all tests
cargo run -- run tests/x.tarn.yaml  # run specific test file
cargo run -- validate          # validate YAML without running
cargo run -- list              # dry run listing
cargo test                     # run all Rust tests
cargo test parser_test         # run a single test module
cargo clippy                   # lint
cargo fmt                      # format

Mandatory Pre-Commit Checks

Always run these commands before every commit and push. Do not skip them — CI will fail otherwise. This has caused repeated CI failures across multiple sessions.

cargo fmt                      # fix formatting FIRST
cargo clippy -- -D warnings    # then fix all warnings
cargo test                     # then verify tests pass

Do not commit or push if any of these fail. Fix the issue, then commit.

Rules Learned From Past Mistakes

Quality gates

• Never suppress linter/clippy warnings with #[allow(...)]. Always fix the root cause — refactor functions, extract structs, simplify signatures. Suppression is not a fix. (User explicitly rejected this approach.)
• Never dismiss a failing test as "flaky" or "pre-existing" without investigating. Read the test, understand why it fails, fix it. Every test failure is a real signal until proven otherwise.
• Do not commit/push with known failing tests. If tests fail, fix them first — even if they look unrelated to your changes.

Verification

• Always verify artifacts from the real production URL/endpoint, never from local files. For install scripts: curl <url> | sh, not sh ./local/path/install.sh. For release assets: download from GitHub releases, not from the local build. (User was frustrated twice by this.)
• When writing or updating docs (README, install instructions), verify every command and URL actually works end-to-end before committing. If a doc references a binary or asset, confirm it exists in the release pipeline.