API Overview

towl is structured as a library (towl crate) with a thin binary wrapper. The library exposes modules for configuration, scanning, parsing, output, and error handling.

Module Map

towl (lib)
├── cli          Command-line argument parsing (clap)
├── comment      TODO types and comment structures
│   ├── todo     TodoType enum, TodoComment struct
│   └── error    TowlCommentError
├── config       Configuration loading and validation
│   ├── types    TowlConfig, ParsingConfig, GitHubConfig, Owner, Repo
│   ├── git      GitRepoInfo (git remote discovery)
│   └── error    TowlConfigError
├── scanner      Directory walking and file filtering
│   ├── types    Scanner, ScanResult
│   └── error    TowlScannerError
├── parser       Regex-based TODO extraction
│   ├── types    Parser, Pattern
│   └── error    TowlParserError
├── output       Formatting and writing results
│   ├── formatter
│   │   ├── formatters   CsvFormatter, JsonFormatter, MarkdownFormatter,
│   │   │                TableFormatter, TomlFormatter
│   │   └── error        FormatterError
│   ├── writer
│   │   ├── writers      StdoutWriter, FileWriter
│   │   └── error        WriterError
│   └── error            TowlOutputError
├── github       GitHub issue creation
│   ├── client   GitHubClient
│   ├── types    CreatedIssue
│   └── error    TowlGitHubError
├── processor    TODO replacement with issue links
│   ├── types    Processor, ProcessorResult
│   └── error    TowlProcessorError
├── llm          LLM-powered TODO validation
│   ├── analyse  analyse_todos, gather_expanded_context
│   ├── claude   ClaudeProvider (Anthropic API)
│   ├── openai   OpenAiProvider (OpenAI-compatible API)
│   ├── cli      ClaudeCodeProvider, CodexProvider (CLI agents)
│   ├── prompt   System prompt and user content construction
│   ├── types    AnalysisResult, AnalysisSummary, Validity, LlmUsage
│   └── error    TowlLlmError
├── tui          Interactive terminal UI
│   ├── app      App, AppMode, SortField, PeekState
│   ├── input    Action, handle_input
│   ├── render   draw
│   └── error    TowlTuiError
└── error        Top-level TowlError (aggregates all error types)

Data Flow

TowlConfig ──► Scanner ──► Parser ──► Output
   │              │            │          │
   │              │            │          ├─ FormatterImpl (enum dispatch)
   │              │            │          └─ WriterImpl (enum dispatch)
   │              │            │
   │              │            └─ Vec<TodoComment>
   │              │
   │              └─ ScanResult { todos, files_scanned, ... }
   │
   ├─ ParsingConfig + GitHubConfig + LlmConfig
   │
   └─ LlmConfig ──► LlmProvider ──► analyse_todos ──► AnalysisSummary

Key Types

Error Hierarchy

TowlError
├── TowlConfigError      Config loading, TOML parsing, git discovery
├── TowlScannerError     File walk, I/O, resource limits
│   └── TowlParserError  Regex compilation, pattern validation
├── TowlOutputError      Formatting, file writing
│   ├── FormatterError   Serialisation failures
│   └── WriterError      I/O, path traversal
├── TowlGitHubError      API errors, auth, rate limiting
├── TowlProcessorError   File replacement errors
├── TowlTuiError         Terminal I/O errors
└── TowlLlmError         LLM API, auth, parsing, I/O

All error types use thiserror for Display and Error trait implementations. Conversion between levels uses #[from] attributes for ergonomic ? propagation.

Constants