Todoctor

Todoctor is a powerful tool for analyzing, tracking, and visualizing technical debt in your codebase using Git. It collects and monitors TODO/FIXME comments in your code, allowing you to observe changes over time.

Why

Developers often leave TODO comments in the code to highlight areas that need improvement or refactoring. However, these comments are rarely converted into tasks in tracking systems.

As a result, todos remain hidden in the codebase and can sit there for years without attention, leading to a hidden backlog of work. This tool tracks these todo comments and prevents them from being forgotten.

Features

• Automatically extracts TODO, FIXME, and other tags from your codebase.
• Supports JavaScript and TypeScript programming languages that Git tracks.
• Analyzes each commit to gather and update comment history.
• Integrates with git blame to track the authorship and timing of changes.
• Visualizes the history of changes to analyze the growth or reduction of technical debt.

Usage

Run the tool in the root directory of your project:

npx todoctor

The program will automatically collect data and display the history of TODO / FIXME comments across commits.

After running the tool, it generates a detailed graph showing the evolution of TODO comments over time. The graph visualizes how many todo comments were added, resolved, or modified across the project's history.

This helps you track the technical debt and maintenance progress at a glance.

In addition to the graph, the tool provides insightful statistics, such as:

• The total number of todo comments.
• The age of the oldest todo.
• The average age of all todos.
• The author with the highest number of todo comments.

These insights help you better understand the state of your codebase and prioritize refactoring efforts.

Finally, the tool generates a detailed list of all todo comments in your project in a tabular format.

The list includes the comment text, the file path, and additional metadata, such as line numbers and authorship information. This list helps you identify, review, and manage unresolved tasks more effectively.

Options

Todoctor supports the following command-line options:

--month <N>

Specifies the number of months to include when tracking TODOs in the repository. If not provided, defaults to 3 months.

Example:

todoctor --months 6

--ignore

Allows you to specify files or directories to ignore during the analysis. This option can be used multiple times.

Example:

todoctor --ignore src/deprecated/ --ignore tests/legacy.test.js

--help

Displays this help message with available options.

--version

Displays the current version of Todoctor.

License

MIT © Azat S.