rusty-todo-md 1.3.0

A multi-language TODO comment extractor for source code files.
Documentation

Rusty TODO MD — A Pre-Commit Hook for Managing TODOs

Rusty TODO MD is a pre-commit hook designed to help you manage and centralize all your code's TODO comments by automatically extracting them and synchronizing them into a single TODO.md file. With support for multiple languages—currently Python, Rust, JavaScript, and Go—Rusty TODO MD now organizes TODOs using a new sectioned format for enhanced readability and easier maintenance.

✨ Key Features

  1. Automatic TODO Collection
    By default, Rusty TODO MD scans your staged files (or all tracked files using the --all-files flag) for markers like TODO and FIXME, and updates your TODO.md with any new entries.

  2. Sectioned TODO.md Format
    The TODO.md file is now organized into sections, grouped first by marker (e.g., # TODO, # FIXME), then by file. Each marker section begins with a header (# <MARKER>), each file with a sub-header (## <file-path>), followed by a list of extracted TODO items.

  3. Multi-line TODO Support
    Handles multi-line and indented TODO comments, merging them into a single entry.

  4. Sync Mechanism

    • Automatically merges new TODO entries with existing ones, using an internal representation.
    • Removes entries when their corresponding TODOs are no longer present in the source code.

  5. Language-Aware Parsing
    Supports precise parsing for Python, Rust, JavaScript, and Go out-of-the-box, with plans for additional languages such as TypeScript, PHP, and Java.

  6. Seamless Pre-Commit Integration
    Easily integrate Rusty TODO MD into your workflow by adding it to your .pre-commit-config.yaml.

🚀 Objective

Scattered TODO comments can be hard to track and maintain. Rusty TODO MD centralizes these comments in a structured, sectioned TODO.md file—making it simpler to review outstanding tasks and keep your documentation in sync with your codebase.

⚙️ Installation & Setup

Option 1: PyPI Installation (Recommended)

Install directly from PyPI using pip:

pip install rusty_todo_md

Then you can use it directly:

rusty-todo-md --help

Option 2: Pre-Commit Hook Integration

With PyPI (Recommended - No Rust toolchain required)

Add the following to your .pre-commit-config.yaml:

repos:
  - repo: https://github.com/simone-viozzi/rusty-todo-md
    rev: v1.1.0  # Use the latest version
    hooks:
      - id: rusty-todo-md
        language: python
        additional_dependencies: ["rusty_todo_md==1.1.0"]

With Git Repository

Add the following snippet to your .pre-commit-config.yaml file at the root of your repository:

repos:
  - repo: https://github.com/simone-viozzi/rusty-todo-md
    rev: v1.1.0  # Use the latest version
    hooks:
      - id: rusty-todo-md

1. Install Pre-Commit

If you haven't already installed pre-commit:

pip install pre-commit

(Alternatively, use your preferred package manager.)

2. Configure Pre-Commit

Add the following snippet to your .pre-commit-config.yaml file at the root of your repository:

repos:
  - repo: https://github.com/simone-viozzi/rusty-todo-md
    rev: v0.1.8-alpha.11
    hooks:
      - id: rusty-todo-md

Replace rev with the desired tag or commit hash.

3. Install the Pre-Commit Hook

Run the following command from your repository root:

pre-commit install

Rusty TODO MD will now run on your staged files each time you commit.

🧩 CLI Usage (Optional)

You can also run Rusty TODO MD manually:

rusty-todo-md --all-files
  • --all-files: Scans all tracked files instead of just the staged ones.
  • --marker/-m: Specify one or more keywords to search for (e.g., TODO, FIXME, HACK). Can be used multiple times.

Example:

rusty-todo-md --markers TODO FIXME HACK

Or specify a custom location for your TODO file:

rusty-todo-md --todo-path docs/TODOS.md

📝 How It Works

  1. File Discovery

    • By default, scans the staged files in your Git index.
    • With the --all-files flag, scans all tracked files in the repository.

  2. Comment Extraction

    • Parses file comments (ignoring code or string literals) to extract markers like TODO and FIXME.
    • Supports multi-line and indented comment structures.

  3. Sectioned TODO.md Format

    • Organizes extracted TODOs into sections grouped by marker and file.
    • Each marker section starts with a header (# <MARKER>), each file with a sub-header (## <file-path>), followed by formatted entries: 
      * [<file-path>:<line_number>](<file-path>#L<line_number>): TODO message

  4. Sync Mechanism

    • Reads the existing TODO.md using the new parser.
    • Merges new TODO entries with the existing ones using an internal representation.
    • Writes the updated, sectioned list back to TODO.md.

🔧 Configuration

  • Markers: The tool searches for TODO by default. You can customize markers (e.g., FIXME, HACK) using the --marker/-m CLI argument. Multiple markers are supported and can be specified multiple times.
  • Language Support: Rusty TODO MD provides built-in parsing for Python (.py), Rust (.rs), JavaScript (.js, .jsx), and Go (.go), with planned support for additional languages.

📊 Test Coverage

Rusty TODO MD maintains comprehensive test coverage to ensure reliability and code quality.

CI/CD Coverage

  • Automated Coverage: Every pull request automatically generates coverage reports
  • Coverage Reports: Available as downloadable artifacts from GitHub Actions
  • Format: Reports are generated in LCOV format for broad tool compatibility

VS Code Integration

For the best local development experience:

  1. Install the Coverage Gutters extension
  2. Run cargo tarpaulin --out Lcov --output-dir ./coverage
  3. Open your project in VS Code to see coverage highlights directly in your source files

📚 Example

Python Example

# TODO: Implement data validation
def process_data(data):
    """
    FIXME: Optimize this logic
        Possibly reduce nested loops
    """
    pass

This produces a section in TODO.md like:

# TODO
## path/to/your_file.py
* [path/to/your_file.py:2](path/to/your_file.py#L2): Implement data validation

# FIXME
## path/to/your_file.py
* [path/to/your_file.py:4](path/to/your_file.py#L4): Optimize this logic Possibly reduce nested loops

Rust Example

// TODO: Refactor main function
fn main() {
    /*
       FIXME: Add error handling
           Possibly a custom result type
    */
}

This produces a section in TODO.md like:

# TODO
## src/main.rs
* [src/main.rs:2](src/main.rs#L2): Refactor main function

# FIXME
## src/main.rs
* [src/main.rs:5](src/main.rs#L5): Add error handling Possibly a custom result type

JavaScript Example

// TODO: Refactor this into separate modules
function init() {
  /* FIXME: Handle edge cases 
     such as null responses */
  fetchData();
}

This produces a section in TODO.md like:

# TODO
## src/app.js
* [src/app.js:1](src/app.js#L1): Refactor this into separate modules

# FIXME
## src/app.js
* [src/app.js:4](src/app.js#L4): Handle edge cases such as null responses

Go Example

// TODO: Add proper logging
func main() {
    /* FIXME: Implement proper error handling
       across the entire application */
    fmt.Println("Hello, World!")
}

This produces a section in TODO.md like:

# TODO
## main.go
* [main.go:1](main.go#L1): Add proper logging

# FIXME
## main.go
* [main.go:3](main.go#L3): Implement proper error handling across the entire application

🤝 Contributing

Contributions are welcome!

  • Open an Issue for bug reports or feature requests.
  • Submit a Pull Request with enhancements, additional language support, or configuration options.

⚖️ License

This project is licensed under the MIT License. You are free to use, modify, and distribute the software as long as the original license is included.

❤️ Support

If you find Rusty TODO MD helpful, please consider giving it a ⭐ on GitHub to help others discover the project.

Happy coding, and let Rusty TODO MD handle your TODOs so you can focus on building amazing features!