npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

todoctor

v1.3.1

Published

CLI tool to analyze and report TODO comments in JavaScript and TypeScript Git repositories

Downloads

929

Readme

Todoctor

Version GitHub License

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.

Report

See an example report.

Todos Graph

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.

Additional Information

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.

List of Todos

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

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. The files in your .gitignore are ignored by default, you don't need to ignore them additionally. This option can be used multiple times.

Example:

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

--include-keywords

Allows you to specify additional keywords in comments that will be treated as technical debt. This option can be used multiple times.

Example:

todoctor --include-keywords eslint-disable-next-line

--exclude-keywords

Allows you to exclude keywords from the report. By default, the following keywords are used to define the technical debt comment:

  • TODO
  • FIXME
  • XXX
  • HACK
  • BUG
  • OPTIMIZE
  • REFACTOR
  • TEMP
  • CHANGED
  • IDEA
  • NOTE
  • REVIEW
  • NB
  • QUESTION
  • DEBUG
  • KLUDGE
  • COMPAT
  • WARNING
  • DANGER
  • INFO
  • DEPRECATED
  • COMBAK

Example:

todoctor --exclude-keywords WARNING --exclude-keywords DEPRECATED

--output-format

You can specify the format of the report. Possible options are html, json and csv. The default value is html.

Example:

todoctor --output-format json

--output

You can define the folder where the report file will be saved. By default it is todoctor folder in the project root.

Example:

todoctor --output report

--help

Displays this help message with available options.

--version

Displays the current version of Todoctor.

License

MIT © Azat S.