towl 0.3.7

A fast CLI tool to scan codebases for TODO comments and output them in multiple formats
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113

# Contributing

## Getting Started

```bash
git clone https://github.com/glottologist/towl.git
cd towl
cargo build
```

### Requirements

- **Rust** 1.75+ (see `rust-toolchain.toml`)
- **git** on `PATH`

## Development Commands

```bash
# Build
cargo build

# Run all tests
cargo nextest run   # preferred
cargo test          # fallback

# Clippy (strict)
cargo clippy --all-targets --all-features

# Format
cargo fmt

# Run the binary
cargo run -- scan
cargo run -- scan -f json -o todos.json
cargo run -- config
cargo run -- init
```

## Project Structure

See [Architecture](./architecture.md) for a full layout. Key entry points:

- `src/bin/towl.rs` -- CLI binary
- `src/lib/mod.rs` -- Library root
- `tests/` -- Integration and property-based tests

## Testing

### Test Hierarchy

Tests follow a strict hierarchy:

1. **proptest** (property-based) -- First choice for pure functions, parsers, validators, serialisation roundtrips
2. **rstest** (parameterized) -- For specific known cases (< 10 inputs with exact expected outputs)
3. **Standalone** -- Last resort, for complex integration scenarios

### Running Tests

```bash
# All tests
cargo nextest run

# Specific module
cargo nextest run scanner

# Property-based tests only
cargo nextest run proptest

# Integration tests only
cargo nextest run --test '*'
```

## Code Style

- Follow Rust naming conventions (`snake_case` for functions, `CamelCase` for types)
- All public items need doc comments (`///`)
- No `#[allow(...)]` attributes -- fix the underlying issue
- No `.unwrap()` / `.expect()` in production code -- use `?` with typed errors
- No `as` numeric casts -- use `try_from` / `into` / `From`
- Minimise `.clone()` -- prefer borrowing, see Clone Reduction Policy

## Error Handling

- Use `thiserror` for error type derivation
- Each module defines its own error enum
- Errors propagate upward via `?` and `#[from]`
- Never silently discard `Result` values

## Adding a New Output Format

1. Create `src/lib/output/formatter/formatters/yourformat.rs`
2. Implement the `Formatter` trait
3. Add a variant to `FormatterImpl` in `formatters/mod.rs`
4. Add dispatch in `FormatterImpl::format()`
5. Add a variant to `OutputFormat` in `src/lib/cli/mod.rs`
6. Update the format-to-writer mapping in `Output::new()`
7. Add tests (proptest for roundtrips, rstest for edge cases)

## Adding a New TODO Type

1. Add a variant to `TodoType` in `src/lib/comment/todo.rs`
2. Update `Display`, `TryFrom<&str>`, `as_filter_str()`
3. Add a default pattern to `default_todo_patterns()` in `src/lib/config/types.rs`
4. Add a pattern mapping in the parser
5. Update tests

## Pull Requests

- Keep PRs focused on a single change
- Include tests for new functionality
- Ensure `cargo clippy` passes with zero warnings
- Ensure `cargo fmt` produces no changes
- Ensure all tests pass