CredoTodoOrDie

credo_todo_or_die is a library with a credo check to allow making notes in code which will fail at an appropriate time. For example:

Get a credo alert when a date/time has arrived:

def get_user(id) do
  # TODO(2022-02-02) Fix this hack when the database migration is complete
  if id > 1_000_000 do
    v1_api_call()
  else
    v2_api_call()
  end
end

This will produce a credo alert on or after the day in question:

┃ [D] → Found a TODO tag: Fix this hack when the database migration is complete (2 days past)
┃       lib/my_app/users.ex:12 #(MyApp.Users)

It is also possible to specify a time with the date:

# TODO(2022-02-02 12:34:56) The time has come!

This can have a more precise description of how long it has been since the note's deadline has passed:

┃ [D] → Found a TODO tag: Fix this hack when the database migration is complete (1 week, 2 days, 6 hours, 16 minutes past)
┃       lib/my_app/users.ex:12 #(MyApp.Users)

Get a credo alert when a package matches a version requirement

# TODO([email protected]) Use the new, cool stuff!
# TODO(phoenix@>=10.0.0) This is the same!

# TODO(jason@~> 2.0.0) Only triggers after 2.0.0 and before 2.1.0

Credo alerts will look like:

┃ [D] ↗ Found a TODO tag: Use the new, cool stuff! (phoenix requirement `>=10.0.0` matched, current version: 10.0.1)
┃       lib/my_app_web/controllers/user_controller.ex:22 #(MyAppWeb.UserController)

Get a credo alert when a GitHub issue / pull request has been closed

# TODO(phoenixframework/phoenix#4321) Refactor when support has been added

Credo alerts will look like:

┃ [D] ↗ Found a TODO tag: Refactor when support has been added (issue #4321 in repo phoenixframework/phoenix has been closed)
┃       lib/my_app/user.ex:22 #(MyApp.User)

Configuration

You can configure one or more versions of the plugin in your .credo.exs file:

%{
  configs: [
    %{
      name: "default",
      checks: [
        {CredoTodoOrDie.Check, tag_name: "BUG", timezone: "Europe/Stockholm", priority: :higher},
        {CredoTodoOrDie.Check, tag_name: "FIXME", timezone: "Europe/Stockholm", priority: :high},
        {CredoTodoOrDie.Check, tag_name: "TODO", timezone: "Europe/Stockholm", priority: :normal},
        # Doesn't show up unless you use the `--strict` flag
        {CredoTodoOrDie.Check, tag_name: "NOTE", timezone: "Europe/Stockholm", priority: :low},

        # If you use `credo_todo_or_die` you'll probably want to disable these built-in checks
        # as it will cause duplicates
        # `credo_todo_or_die` will report standard notes (without parentheses) for the above `tag_name`s
        {Credo.Check.Design.TagTODO, false},
        {Credo.Check.Design.TagFIXME, false}
      ],
    }
  ]
}

The timezone param defaults to "Etc/UTC". It allows you to set the timezone of your development / CI machine for more accurate reporting of notes based on time.

Caveats

While this checker is inspired by the ruby todo_or_die gem, it doesn't execute at runtime and can't do everything that gem can. For example we can't fail on a condition defined by runtime code.

Potential future improvements

• Notes which reference a dependency version and alert when it has been reached (see here)

• Notes which reference an OTP / Elixir version and alert when it has been reached

• Notes like TODO(#1234) xxxxx which can alert when a specific GitHub(/other) issue is closed

Installation

If available in Hex, the package can be installed by adding credo_todo_or_die to your list of dependencies in mix.exs:

def deps do
  [
    {:credo_todo_or_die, "~> 0.3.0"}
  ]
end

Documentation can be generated with ExDoc and published on HexDocs. Once published, the docs can be found at https://hexdocs.pm/credo_todo_or_die.