TaskValidator
View SourceA library for validating Markdown task lists against a structured format specification.
Installation
Add task_validator
to your list of dependencies in mix.exs
:
def deps do
[
{:task_validator, "~> 0.6.0"}
]
end
Usage
Command Line
# Validate the default TaskList.md file
mix validate_tasklist
# Validate a custom file path
mix validate_tasklist --path ./path/to/custom/TaskList.md
# Create a new task list template
mix create_template
# Create a template with custom prefix
mix create_template --prefix SSH
# Create a template for a specific category
mix create_template --category features
mix create_template --category documentation
Programmatic
case TaskValidator.validate_file("path/to/tasklist.md") do
{:ok, message} ->
IO.puts("Success: #{message}")
{:error, reason} ->
IO.puts("Error: #{reason}")
end
Format Specification
The TaskValidator enforces a specific format for task lists with a strong focus on error handling:
- Task IDs must follow a consistent pattern: 2-4 uppercase letters followed by 3-4 digits (e.g., SSH0001, SCP0001, ERR001, REF0002)
- Subtasks can use either numeric suffixes (SSH0001-1) or letter suffixes for checkbox style (SSH0001a)
- Checkbox subtasks are supported:
- [ ] Subtask description [SSH0001a]
- Dependencies field tracks relationships between tasks
- Code Quality KPIs enforce limits: max 5 functions/module, 15 lines/function, call depth 2
- Task categories with specific number ranges:
- Core infrastructure: 1-99
- Features: 100-199
- Documentation: 200-299
- Testing: 300-399
- Main tasks and subtasks have different error handling section requirements:
- Main tasks: Comprehensive error handling documentation including GenServer specifics
- Subtasks: Simplified error handling focused on task-specific approaches
- Other required sections include Description, Status, Priority, Dependencies, etc.
- Tasks marked as "In Progress" must have subtasks
- Review ratings must follow the specified format (1-5 scale)
- Support for reference definitions to reduce repetition (e.g., {{error-handling-main}})
Error Handling Requirements
Main tasks must include the following comprehensive error handling sections (or use the {{error-handling-main}}
reference):
**Error Handling**
**Core Principles**
- Pass raw errors
- Use {:ok, result} | {:error, reason}
- Let it crash
**Error Implementation**
- No wrapping
- Minimal rescue
- function/1 & /! versions
**Error Examples**
- Raw error passthrough
- Simple rescue case
- Supervisor handling
**GenServer Specifics**
- Handle_call/3 error pattern
- Terminate/2 proper usage
- Process linking considerations
Or simply use: {{error-handling-main}}
Subtasks have a simplified error handling format:
**Error Handling**
**Task-Specific Approach**
- Error pattern for this task
**Error Reporting**
- Monitoring approach
Or use: {{error-handling-subtask}}
Dependencies
Tasks can specify dependencies on other tasks using the Dependencies field:
**Dependencies**
- SSH0001 (Authentication must be complete)
- ERR001 (Error handling framework required)
The validator ensures all referenced tasks exist in the task list.
Checkbox Subtasks
Subtasks can use checkbox format for better visual tracking:
## Task Details
### SSH0001: SSH Session Initialization
**Subtasks**
- [x] Connection setup [SSH0001a]
- [ ] Authentication flow [SSH0001b]
- [ ] Session establishment [SSH0001c]
Code Quality KPIs
All tasks must include code quality metrics that adhere to these limits:
- Maximum functions per module: 5
- Maximum lines per function: 15
- Maximum call depth: 2
**Code Quality KPIs**
- Functions per module: 3
- Lines per function: 12
- Call depth: 2
Or use: {{standard-kpis}}
Reference Definitions
To reduce repetition in task lists, you can define reusable content blocks:
## Reference Definitions
### error-handling-main
**Error Handling**
**Core Principles**
- Pass raw errors
...
### standard-kpis
**Code Quality KPIs**
- Functions per module: 3
...
Then use them in tasks with {{reference-name}}
:
### SSH0001: Some task
**Dependencies**
- None
{{standard-kpis}}
{{error-handling-main}}
**Status**: Planned
This significantly reduces file size and maintains consistency across tasks.
Task Categories
Tasks are organized into categories based on their ID number:
- Core Infrastructure (1-99): Essential system components
- Features (100-199): User-facing functionality
- Documentation (200-299): Documentation tasks
- Testing (300-399): Test implementation
Each category has specific required sections. For example, feature tasks require:
- Feature Specification
- User Impact
- Integration Points
Documentation tasks require:
- Documentation Scope
- Target Audience
- Related Documents
Multi-Project Support
The task validator supports multiple project prefixes in the same task list. Each prefix typically represents a different component or subproject:
## Current Tasks
| ID | Description | Status | Priority |
| ------- | -------------------- | ----------- | -------- |
| SSH0001 | SSH authentication | In Progress | High |
| SCP0001 | File transfer module | Planned | Medium |
| ERR001 | Error handling | In Progress | High |
The validator ensures consistency within each task hierarchy, so a task with ID "SSH0001" must have subtasks with IDs like "SSH0001-1", "SSH0001-2", etc.
Example Files
The repository includes several example files in the test/fixtures
directory:
sample_tasklist.md
- A basic valid task listmulti_prefix_tasklist.md
- A valid task list with multiple project prefixesprefix_mismatch.md
- Demonstrates prefix mismatch validation (subtask has different prefix than parent)invalid_rating.md
- Shows validation of review rating formatinvalid_mix_prefixes.md
- Contains various validation errors
You can test validation against these examples:
mix validate_tasklist --path test/fixtures/multi_prefix_tasklist.md # Should pass
mix validate_tasklist --path test/fixtures/prefix_mismatch.md # Should fail
License
MIT License
Documentation can be generated with ExDoc and published on HexDocs. Once published, the docs can be found at https://hexdocs.pm/task_validator.