json-archive/CLAUDE.md

## Running Tests

### Unit tests

```bash
cargo test                         # Run without compression support
cargo test --features compression  # Run with compression support
```

### Integration tests

The compression integration tests verify appending to compressed archives (gzip, brotli, zstd):

```bash
cd tests/compression-integration
./run_all.sh      # Run all compression tests
./run_gzip_test.sh   # Run only gzip test
./run_brotli_test.sh # Run only brotli test
./run_zstd_test.sh   # Run only zstd test
```

These tests:
1. Create an uncompressed archive from the first state file
2. Compress it with the respective tool (gzip/brotli/zstd)
3. Append additional state files to the compressed archive
4. Verify the archive can be read and shows the correct observation count

Requirements: Python 3 (for test data generation), gzip, brotli, zstd command-line tools.

### Fuzz testing

To begin fuzzing, run: `cargo fuzz run <fuzz target name>`

The source code for a fuzz target by default lives in `fuzz/fuzz_targets/<fuzz target name>.rs`.

Each fuzz target is a Rust program that is given random data and tests a crate (in this case, json-archive). Use `cargo fuzz list` to view the list of all existing fuzz targets:

## Documentation Style Guidelines

When writing command documentation, follow the Dutch engineer approach:

### Structure and Content
- Lead with what the command actually does (one clear sentence)
- Show real examples using actual demo files from the project
- Include both human-readable and machine-readable output modes
- Include practical use cases with actual bash/jq examples for scripting
- Be upfront about performance characteristics and limitations
- Document known bugs/issues directly instead of hiding them

### Tone and Communication
- Be direct and practical, not promotional
- Don't apologize for limitations. Just state them clearly so engineers can make informed decisions
- Use real scenarios, not toy examples
- Focus on what engineers actually need to know to use the tool effectively
- Include error cases and what they mean
- Provide concrete examples that can be copy-pasted and run

### Example sections to include
1. **Purpose**: One sentence explaining what it does
2. **Basic usage**: Simple examples first
3. **Output modes**: When to use human vs JSON output
4. **Practical use cases**: Real scenarios with working code
5. **Performance characteristics**: Memory/CPU usage expectations
6. **Error cases**: Common failures and what they mean
7. **Known issues**: Bugs or limitations stated directly