Packages
A library for validating Markdown task lists with structured format specifications. Features: checkbox subtasks, dependencies, code quality KPIs, task categories, multi-project prefixes, and comprehensive error handling documentation.
Current section
16 Versions
Jump to
Current section
16 Versions
Compare versions
5
files changed
+260
additions
-11
deletions
| @@ -24,6 +24,12 @@ mix validate_tasklist | |
| 24 24 | |
| 25 25 | # Validate a custom file path |
| 26 26 | mix validate_tasklist --path ./path/to/custom/TaskList.md |
| 27 | + |
| 28 | + # Create a new task list template |
| 29 | + mix create_template |
| 30 | + |
| 31 | + # Create a template with custom prefix |
| 32 | + mix create_template --prefix SSH |
| 27 33 | ``` |
| 28 34 | |
| 29 35 | ### Programmatic |
| @@ -2,14 +2,15 @@ | |
| 2 2 | [{<<"Docs">>,<<"https://hexdocs.pm/task_validator">>}, |
| 3 3 | {<<"GitHub">>,<<"https://github.com/ZenHive/task_validator">>}]}. |
| 4 4 | {<<"name">>,<<"task_validator">>}. |
| 5 | - {<<"version">>,<<"0.3.0">>}. |
| 5 | + {<<"version">>,<<"0.4.0">>}. |
| 6 6 | {<<"description">>, |
| 7 7 | <<"A library for validating Markdown task lists against a structured format specification.\nSupports multiple project prefixes (SSH0001, SCP0001, ERR001, etc.) while ensuring\nconsistent task tracking with proper ID formats, required sections, and status values.">>}. |
| 8 8 | {<<"elixir">>,<<"~> 1.18">>}. |
| 9 9 | {<<"app">>,<<"task_validator">>}. |
| 10 10 | {<<"files">>, |
| 11 11 | [<<"lib">>,<<"lib/mix">>,<<"lib/mix/tasks">>, |
| 12 | - <<"lib/mix/tasks/validate_tasklist.ex">>,<<"lib/task_validator.ex">>, |
| 12 | + <<"lib/mix/tasks/validate_tasklist.ex">>, |
| 13 | + <<"lib/mix/tasks/create_template.ex">>,<<"lib/task_validator.ex">>, |
| 13 14 | <<".formatter.exs">>,<<"mix.exs">>,<<"README.md">>,<<"LICENSE">>]}. |
| 14 15 | {<<"licenses">>,[<<"MIT">>]}. |
| 15 16 | {<<"requirements">>,[]}. |
| @@ -0,0 +1,190 @@ | |
| 1 | + defmodule Mix.Tasks.TaskValidator.CreateTemplate do |
| 2 | + @moduledoc """ |
| 3 | + Creates a template TaskList.md file with example tasks. |
| 4 | + |
| 5 | + This task generates a new TaskList.md file with example tasks that follow |
| 6 | + the required structure and format specifications. Use this as a starting |
| 7 | + point for your own task list. |
| 8 | + |
| 9 | + ## Usage |
| 10 | + |
| 11 | + mix task_validator.create_template [OPTIONS] |
| 12 | + |
| 13 | + ## Options |
| 14 | + |
| 15 | + --path Path where to create the TaskList.md file (default: ./TaskList.md) |
| 16 | + --prefix Project prefix for example tasks (default: PRJ) |
| 17 | + |
| 18 | + ## Example |
| 19 | + |
| 20 | + mix task_validator.create_template |
| 21 | + mix task_validator.create_template --path ./docs/TaskList.md --prefix SSH |
| 22 | + """ |
| 23 | + |
| 24 | + use Mix.Task |
| 25 | + |
| 26 | + @template """ |
| 27 | + # Project Task List |
| 28 | + |
| 29 | + ## Current Tasks |
| 30 | + |
| 31 | + | ID | Description | Status | Priority | Assignee | Review Rating | |
| 32 | + | --- | --- | --- | --- | --- | --- | |
| 33 | + | <%= @prefix %>0001 | Implement core functionality | In Progress | High | - | - | |
| 34 | + | <%= @prefix %>0002 | Add documentation framework | Planned | Medium | - | - | |
| 35 | + |
| 36 | + ## Completed Tasks |
| 37 | + |
| 38 | + | ID | Description | Status | Completed By | Review Rating | |
| 39 | + | --- | --- | --- | ------------ | ------------- | |
| 40 | + | <%= @prefix %>0003 | Project setup | Completed | @developer | 4.5 | |
| 41 | + |
| 42 | + ## Active Task Details |
| 43 | + |
| 44 | + ### <%= @prefix %>0001: Implement core functionality |
| 45 | + |
| 46 | + **Description** |
| 47 | + Develop and implement the core functionality with a focus on maintainability and extensibility. |
| 48 | + |
| 49 | + **Simplicity Progression Plan** |
| 50 | + 1. Create basic structure |
| 51 | + 2. Add essential features |
| 52 | + 3. Implement error handling |
| 53 | + 4. Add extensibility points |
| 54 | + |
| 55 | + **Simplicity Principle** |
| 56 | + Design with simplicity and clarity as primary goals. Start with minimal functionality |
| 57 | + and add features incrementally based on validated needs. |
| 58 | + |
| 59 | + **Abstraction Evaluation** |
| 60 | + Medium - provides necessary abstractions while keeping interfaces clear and intuitive |
| 61 | + |
| 62 | + **Requirements** |
| 63 | + - Core functionality implementation |
| 64 | + - Error handling |
| 65 | + - Performance considerations |
| 66 | + - Documentation |
| 67 | + - Tests coverage |
| 68 | + |
| 69 | + **ExUnit Test Requirements** |
| 70 | + - Unit tests for core functions |
| 71 | + - Integration tests for key workflows |
| 72 | + - Performance benchmarks |
| 73 | + - Error condition tests |
| 74 | + |
| 75 | + **Integration Test Scenarios** |
| 76 | + - Happy path workflows |
| 77 | + - Error handling cases |
| 78 | + - Edge case scenarios |
| 79 | + - Performance under load |
| 80 | + |
| 81 | + **Typespec Requirements** |
| 82 | + - Define types for core functions |
| 83 | + - Document type constraints |
| 84 | + - Ensure proper type coverage |
| 85 | + |
| 86 | + **TypeSpec Documentation** |
| 87 | + Types should be clearly documented with examples and usage patterns |
| 88 | + |
| 89 | + **TypeSpec Verification** |
| 90 | + Use Dialyzer to verify type correctness |
| 91 | + |
| 92 | + **Status**: In Progress |
| 93 | + **Priority**: High |
| 94 | + |
| 95 | + #### 1. Basic structure implementation (<%= @prefix %>0001-1) |
| 96 | + |
| 97 | + **Description** |
| 98 | + Create the foundational structure and interfaces |
| 99 | + |
| 100 | + **Status**: Completed |
| 101 | + **Review Rating**: 4.5 |
| 102 | + |
| 103 | + #### 2. Essential features (<%= @prefix %>0001-2) |
| 104 | + |
| 105 | + **Description** |
| 106 | + Implement core features and functionality |
| 107 | + |
| 108 | + **Status**: In Progress |
| 109 | + |
| 110 | + ### <%= @prefix %>0002: Add documentation framework |
| 111 | + |
| 112 | + **Description** |
| 113 | + Set up and implement the documentation framework for the project. |
| 114 | + |
| 115 | + **Simplicity Progression Plan** |
| 116 | + 1. Set up documentation tools |
| 117 | + 2. Create basic structure |
| 118 | + 3. Add API documentation |
| 119 | + 4. Create user guides |
| 120 | + |
| 121 | + **Simplicity Principle** |
| 122 | + Keep documentation clear, concise, and maintainable |
| 123 | + |
| 124 | + **Abstraction Evaluation** |
| 125 | + Low - straightforward documentation structure |
| 126 | + |
| 127 | + **Requirements** |
| 128 | + - Documentation tool setup |
| 129 | + - API documentation |
| 130 | + - User guides |
| 131 | + - Example code |
| 132 | + |
| 133 | + **ExUnit Test Requirements** |
| 134 | + - Documentation generation tests |
| 135 | + - Link validation |
| 136 | + - Code example tests |
| 137 | + |
| 138 | + **Integration Test Scenarios** |
| 139 | + - Documentation generation |
| 140 | + - Format validation |
| 141 | + - Cross-reference checks |
| 142 | + |
| 143 | + **Typespec Requirements** |
| 144 | + - Document type specifications |
| 145 | + - Include type examples |
| 146 | + |
| 147 | + **TypeSpec Documentation** |
| 148 | + Clear documentation of all public types |
| 149 | + |
| 150 | + **TypeSpec Verification** |
| 151 | + Regular verification of documentation accuracy |
| 152 | + |
| 153 | + **Status**: Planned |
| 154 | + **Priority**: Medium |
| 155 | + """ |
| 156 | + |
| 157 | + def run(args) do |
| 158 | + {options, _, _} = OptionParser.parse(args, strict: [path: :string, prefix: :string]) |
| 159 | + path = options[:path] || "TaskList.md" |
| 160 | + prefix = options[:prefix] || "PRJ" |
| 161 | + |
| 162 | + if File.exists?(path) do |
| 163 | + Mix.shell().yes?("File #{path} already exists. Overwrite?") || exit(:normal) |
| 164 | + end |
| 165 | + |
| 166 | + content = EEx.eval_string(@template, assigns: [prefix: prefix]) |
| 167 | + |
| 168 | + case File.write(path, content) do |
| 169 | + :ok -> |
| 170 | + Mix.shell().info("✅ Created template task list at #{path}") |
| 171 | + validate_template(path) |
| 172 | + |
| 173 | + {:error, reason} -> |
| 174 | + Mix.shell().error("Failed to create template: #{:file.format_error(reason)}") |
| 175 | + exit({:shutdown, 1}) |
| 176 | + end |
| 177 | + end |
| 178 | + |
| 179 | + defp validate_template(path) do |
| 180 | + case TaskValidator.validate_file(path) do |
| 181 | + {:ok, _} -> |
| 182 | + Mix.shell().info("✅ Template validation successful!") |
| 183 | + |
| 184 | + {:error, reason} -> |
| 185 | + Mix.shell().error("⚠️ Generated template failed validation: #{reason}") |
| 186 | + Mix.shell().error("Please report this as a bug") |
| 187 | + exit({:shutdown, 1}) |
| 188 | + end |
| 189 | + end |
| 190 | + end |
| @@ -2,12 +2,61 @@ defmodule Mix.Tasks.ValidateTasklist do | |
| 2 2 | @moduledoc """ |
| 3 3 | Validates the format and structure of a TaskList.md file. |
| 4 4 | |
| 5 | - Validates that task lists follow the required format: |
| 6 | - - Task IDs must follow a consistent pattern: 2-4 uppercase letters followed by 3-4 digits |
| 7 | - - Subtasks must use the same prefix as their parent task |
| 8 | - - Required sections are present for each task |
| 9 | - - Tasks marked as "In Progress" have at least one subtask |
| 10 | - - Completed subtasks have a valid review rating |
| 5 | + ## Task List Structure |
| 6 | + The task list must contain two main sections: |
| 7 | + - Current Tasks (Active tasks in progress) |
| 8 | + - Completed Tasks (Tasks that have been finished) |
| 9 | + |
| 10 | + ## Validation Rules |
| 11 | + |
| 12 | + ### Task ID Format |
| 13 | + - 2-4 uppercase letters as prefix (e.g., SSH, SCP, ERR) |
| 14 | + - 3-4 digits as sequence number |
| 15 | + - Optional hyphen and number for subtasks (e.g., SSH0001-1) |
| 16 | + - Examples: SSH0001, SCP0001, ERR001, SSH0001-1 |
| 17 | + |
| 18 | + ### Status Values |
| 19 | + Valid statuses: |
| 20 | + - Planned |
| 21 | + - In Progress |
| 22 | + - Review |
| 23 | + - Completed |
| 24 | + - Blocked |
| 25 | + |
| 26 | + ### Priority Values |
| 27 | + Valid priorities: |
| 28 | + - Critical |
| 29 | + - High |
| 30 | + - Medium |
| 31 | + - Low |
| 32 | + |
| 33 | + ### Required Sections |
| 34 | + Main tasks must include: |
| 35 | + - Description |
| 36 | + - Simplicity Progression Plan |
| 37 | + - Simplicity Principle |
| 38 | + - Abstraction Evaluation |
| 39 | + - Requirements |
| 40 | + - ExUnit Test Requirements |
| 41 | + - Integration Test Scenarios |
| 42 | + - Typespec Requirements |
| 43 | + - TypeSpec Documentation |
| 44 | + - TypeSpec Verification |
| 45 | + - Status |
| 46 | + - Priority |
| 47 | + |
| 48 | + ### Subtask Requirements |
| 49 | + - Must use same prefix as parent task |
| 50 | + - Must have "Status" section |
| 51 | + - If status is "Completed", must have "Review Rating" |
| 52 | + - Review rating format: 1-5 with optional decimal (e.g., 4.5) |
| 53 | + - Review rating can include "(partial)" suffix |
| 54 | + |
| 55 | + ### Additional Rules |
| 56 | + - Tasks marked as "In Progress" must have at least one subtask |
| 57 | + - All non-completed tasks must have detailed entries |
| 58 | + - No duplicate task IDs allowed |
| 59 | + - All subtasks must use the same prefix as their parent task |
| 11 60 | |
| 12 61 | ## Usage |
| 13 62 | |
| @@ -15,7 +64,7 @@ defmodule Mix.Tasks.ValidateTasklist do | |
| 15 64 | |
| 16 65 | ## Options |
| 17 66 | |
| 18 | - --path Specify a non-default path to the TaskList.md file |
| 67 | + --path Specify a non-default path to the TaskList.md file (default: docs/TaskList.md) |
| 19 68 | |
| 20 69 | ## Example |
| @@ -4,7 +4,7 @@ defmodule TaskValidator.MixProject do | |
| 4 4 | def project do |
| 5 5 | [ |
| 6 6 | app: :task_validator, |
| 7 | - version: "0.3.0", |
| 7 | + version: "0.4.0", |
| 8 8 | elixir: "~> 1.18", |
| 9 9 | start_permanent: Mix.env() == :prod, |
| 10 10 | description: description(), |
| @@ -65,7 +65,10 @@ defmodule TaskValidator.MixProject do | |
| 65 65 | ], |
| 66 66 | groups_for_modules: [ |
| 67 67 | Core: [TaskValidator], |
| 68 | - Tasks: [Mix.Tasks.ValidateTasklist] |
| 68 | + Tasks: [ |
| 69 | + Mix.Tasks.ValidateTasklist, |
| 70 | + Mix.Tasks.TaskValidator.CreateTemplate |
| 71 | + ] |
| 69 72 | ] |
| 70 73 | ] |
| 71 74 | end |