TaskValidator

A library for validating Markdown task lists against a structured format specification, with enhanced support for Elixir/Phoenix projects.

Installation

Add task_validator to your list of dependencies in mix.exs:

def deps do
  [
    {:task_validator, "~> 0.9.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 task_validator.create_template

# Create a template with custom prefix
mix task_validator.create_template --prefix SSH

# Create a template for a specific category (Elixir/Phoenix categories)
mix task_validator.create_template --category otp_genserver
mix task_validator.create_template --category phoenix_web
mix task_validator.create_template --category testing

# Use semantic prefixes automatically
mix task_validator.create_template --semantic --category phoenix_web

Programmatic

# Simple validation
case TaskValidator.validate_file("path/to/tasklist.md") do
  {:ok, message} ->
    IO.puts("Success: #{message}")
  {:error, reason} ->
    IO.puts("Error: #{reason}")
end

# Detailed validation with custom validators
validators = [
  TaskValidator.Validators.IdValidator,
  TaskValidator.Validators.StatusValidator,
  TaskValidator.Validators.KpiValidator
]

case TaskValidator.validate_file_with_pipeline("path/to/tasklist.md", validators) do
  {:ok, result} ->
    IO.puts("Valid: #{result.valid?}")
    IO.puts("Warnings: #{length(result.warnings)}")
  {:error, reason} ->
    IO.puts("Error: #{reason}")
end

Configuration

TaskValidator supports extensive configuration options. You can customize validation rules by adding settings to your config/config.exs:

config :task_validator,
  valid_statuses: ["Todo", "Doing", "Done"],
  max_functions_per_module: 7,
  max_lines_per_function: 20

See the Configuration Guide for all available options.

Format Specification

The TaskValidator enforces a specific format for task lists with a strong focus on error handling:

Error Handling Requirements

Main tasks must include the following comprehensive error handling sections:

**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

Subtasks have a simplified error handling format:

**Error Handling**
**Task-Specific Approach**
- Error pattern for this task
**Error Reporting**
- Monitoring approach

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.

Subtask Formats

Subtasks can be organized in two formats:

Checkbox Format (Simplified):

### SSH0001: SSH Session Initialization

**Subtasks**
- [x] Implement password authentication [SSH0001a]
- [ ] Add key-based authentication [SSH0001b]
- [ ] Implement host verification [SSH0001c]

This format provides immediate visual feedback on task progress and is ideal for minor subtasks or quick checklists.

Numbered Format (Full sections):

#### 1. Implement password authentication (SSH0001-1)
**Description**
Create password-based authentication mechanism with secure credential handling

**Status**
Completed

**Review Rating**
4.5

{{error-handling-subtask}}

The numbered format is recommended for significant subtasks that need detailed tracking. Both formats are valid and can be mixed within the same task list. See docs/examples/ for complete working examples demonstrating both formats.

Code Quality KPIs

All tasks must include code quality metrics that adhere to these limits:

**Code Quality KPIs**
- Functions per module: 3
- Lines per function: 12
- Call depth: 2

Reference Definitions (Content Placeholders)

References are a powerful feature to reduce file size by 60-70% while maintaining consistency. They work as content placeholders that the validator recognizes but doesn't expand.

Define references at the end of your task list:

## References

## #{{error-handling}}
**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

## #{{standard-kpis}}
**Code Quality KPIs**
- Functions per module: ≤ 10
- Lines per function: ≤ 20
- Call depth: ≤ 3

Then use them in tasks with {{reference-name}}:

### SSH0001: Implement SSH connection module

**Description**: Create core SSH connection module
**Requirements**: TCP connection, SSH handshake
{{test-requirements}}
{{typespec-requirements}}
{{def-no-dependencies}}
{{standard-kpis}}
{{error-handling}}
**Status**: In Progress
**Priority**: High

Key points about references:

See /docs/example_tasklist_with_references.md for a complete working example.

Task Categories

For Elixir/Phoenix projects, tasks are organized into semantic categories:

Category ID Range Prefix Description
OTP/GenServer 0001-0099 OTP Process management, supervisors, state machines
Phoenix Web 0100-0199 PHX Controllers, LiveView, routes, plugs
Business Logic 0200-0299 CTX Contexts, domain logic, business rules
Data Layer 0300-0399 DB Schemas, migrations, queries, repos
Infrastructure 0400-0499 INF Deployment, monitoring, configuration
Testing 0500-0599 TST Test implementation, coverage, CI/CD

Each category has specific required sections tailored to its domain. For example:

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:

Complete Task List Examples (docs/examples/)

Full working examples for different project categories:

Each example demonstrates proper subtask formatting, including both numbered subtasks with full sections and checkbox format for minor items. See docs/examples/README.md for detailed explanations.

Documentation

Test Fixtures (test/fixtures/)

Validation test cases:

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.