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
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130

# Types

Core data types used across the towl library.

## `TodoType`

```rust
pub enum TodoType {
    Todo,
    Fixme,
    Hack,
    Note,
    Bug,
}
```

Represents the category of a TODO comment.

### Display

| Variant | Display |
|---------|---------|
| `Todo` | `TODO` |
| `Fixme` | `FIXME` |
| `Hack` | `HACK` |
| `Note` | `NOTE` |
| `Bug` | `BUG` |

### `as_filter_str`

```rust
pub const fn as_filter_str(&self) -> &'static str
```

Returns the lowercase filter string used for CLI filtering:

| Variant | Filter string |
|---------|---------------|
| `Todo` | `"todo"` |
| `Fixme` | `"fixme"` |
| `Hack` | `"hack"` |
| `Note` | `"note"` |
| `Bug` | `"bug"` |

### Conversions

- `TryFrom<&str>` -- Case-insensitive conversion from string
- `clap::ValueEnum` -- CLI argument parsing

### Trait Implementations

`Debug`, `Clone`, `Copy`, `PartialEq`, `Eq`, `Hash`, `Serialize`, `Deserialize`, `ValueEnum`

## `TodoComment`

```rust
pub struct TodoComment {
    pub id: String,
    pub file_path: PathBuf,
    pub line_number: usize,
    pub column_start: usize,
    pub column_end: usize,
    pub todo_type: TodoType,
    pub original_text: String,
    pub description: String,
    pub context_lines: Vec<String>,
    pub function_context: Option<String>,
    pub analysis: Option<AnalysisResult>,
}
```

A single TODO comment extracted from a source file.

| Field | Description |
|-------|-------------|
| `id` | Unique identifier (generated per extraction) |
| `file_path` | Path to the source file |
| `line_number` | 1-based line number |
| `column_start` | 0-based start column of the TODO marker |
| `column_end` | 0-based end column of the TODO marker |
| `todo_type` | Category (`Todo`, `Fixme`, etc.) |
| `original_text` | The full original comment line |
| `description` | Extracted description text after the marker |
| `context_lines` | Surrounding source lines (configurable window) |
| `function_context` | Enclosing function name, if detected |
| `analysis` | LLM validation result, populated when `--ai` is used (skipped during serialisation if `None`) |

### Trait Implementations

`Debug`, `Clone`, `PartialEq`, `Serialize`, `Deserialize`

## `ScanResult`

```rust
pub struct ScanResult {
    pub todos: Vec<TodoComment>,
    pub files_scanned: usize,
    pub files_skipped: usize,
    pub files_errored: usize,
    pub duration: std::time::Duration,
}
```

Returned by `Scanner::scan()`. See [Scanner](./scanner.md) for details.

## `Owner` / `Repo`

Newtype wrappers for GitHub owner and repository names:

```rust
pub struct Owner(String);
pub struct Repo(String);
```

Both provide `try_new(impl Into<String>) -> Result<Self, TowlConfigError>` (validates length) and `Display`. See [Config](./config.md) for details.

## `OutputFormat`

```rust
pub enum OutputFormat {
    Table,
    Json,
    Csv,
    Toml,
    Markdown,
    Terminal,
}
```

CLI-facing enum for selecting output format. `Table` and `Terminal` produce identical output. See [Output](./output.md) for details.