johninamillion/todo

A powerful CLI tool to scan your source code for open tasks — with user filtering, Git integration, and customizable reporting.

0.1.0 2025-09-27 20:28 UTC

Requires

• php: ^8.3
• johninamillion/php-git: ^0.1.0
• symfony/console: ^6.2|^7.0
• symfony/process: ^6.2|^7.0

Requires (Dev)

• johninamillion/php-code-styles: ^0.2.0
• phpunit/phpunit: ^12.0
• roave/security-advisories: dev-latest

MIT

• johninamillion

README

A powerful CLI tool to scan your source code for open tasks.

Table of Contents

• Installation
• Features
• Usage
• Development
• License

Installation

Install the package globally or per-project via Composer:

composer require johninamillion/todo

You can also link the CLI binary directly:

chmod +x bin/todo

Features

• Detects BUG, FIX, TODO, and TEST annotations in comments.
• Filter by:
  • keyword (--keywords)
  • type (--bugs, --fixes, --tests and --todos)
  • user (--user or --me)
• Git-aware:
  • Honors .gitignore by default
  • Use your Git username with --me
• Optional flags:
  • --fail-on-bugs, --fail-on-fixes
  • --display-time
  • --include-dotfiles, --include-ignored

Usage

Scan your current directory for all relevant tags:

./bin/todo

Options

Option	Description
[path]	Scan a specific directory (default: current)
--exclude=DIRS	Comma-separated list of directories to exclude
--keywords=...	Comma-separated list of keywords to match
--user=USERNAME	Only show entries assigned to a specific user
--me	Use your Git username to filter results
--bugs	Only show entries tagged with BUG
--fixes	Only show entries tagged with FIX
--tests	Only show entries tagged with TEST
--todos	Only show entries tagged with TODO
--display-time	Show the last modification time for each entry
--fail-on-bugs	Return non-zero exit code if any BUGs are found
--fail-on-fixes	Return non-zero exit code if any FIXes are found
--include-dotfiles	Include hidden files (e.g., .env, .github)
--include-ignored	Include files ignored by .gitignore

Example Comment Format

Works with line comments:

// BUG @john-doe This is a critical issue.
// FIX @jane-dev Applied hotfix.
// TODO @backend-team Improve validation.
// TEST @qa-user Add coverage for edge case.

Also works with block comments:

/**
 * BUG @me Something is broken.
 * FIX @teammate Refactor needed.
 */

Example Commands

Scan with bug-only filter:

./bin/todo --bugs

Scan with custom keywords and show timestamps:

./bin/todo --keywords=security,performance --display-time

Scan only your assigned items (via Git):

./bin/todo --me

Fail build on any FIX or BUG:

./bin/todo --fail-on-bugs --fail-on-fixes

Configuration via composer.json

You may add these scripts for convenience:

{
    "scripts": {
        "todo": "./bin/todo --display-time",
        "todo:me": "./bin/todo --me --display-time"
    }
}

Development

Analyze Code

To analyze your code for potential issues, you can run phpstan:

composer code:analyse

Apply Code-Styles

To ensure your code adheres to the coding standards, you can run the php-cs-fixer.

composer code:format

Run Tests

To run the tests, make sure you have installed phpunit within the dev dependencies and then run:

composer test

Check the Test Coverage:

composer test:coverage

License

This package is licensed under the MIT License. See the LICENSE file for full details.

All Glory To God - The Father, The Son, and The Holy Spirit.