Metadata-Version: 2.4
Name: todo-linter
Version: 1.0.9
Summary: Ensure to-do items in your code have an owner and an issue.
Keywords: lint,linter,to-do
Author: Chris Herborth
Author-email: Chris Herborth <chrish@pobox.com>
License-Expression: CC-BY-NC-SA-4.0
License-File: LICENSE
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Dist: coverage ; extra == 'coverage'
Maintainer: Chris Herborth
Maintainer-email: Chris Herborth <chrish@pobox.com>
Requires-Python: >=3.11
Project-URL: documentation, https://worktree.ca/taffer/todo-linter/src/branch/main/README.md
Project-URL: homepage, https://worktree.ca/taffer/todo-linter/
Project-URL: issues, https://worktree.ca/taffer/todo-linter/issues
Project-URL: source, https://worktree.ca/taffer/todo-linter/
Provides-Extra: coverage
Description-Content-Type: text/markdown

# todo-linter

Ensure to-do items in your code have an owner and an issue.

This is inspired by the
[`todo_linter.py`](https://github.com/isaracorp/isara-linters/blob/develop/todo_linter.py)
I wrote several years ago for [ISARA](https://www.isara.com/).

`todo-linter` searches for various "TODO" <!-- todo-linter: ignore --> tags in
the given files, and complains if they don't include an *owner* and a
*reference* to an issue or task describing the deferred work:

```c
// TODO(chrish@pobox.com https://worktree.ca/taffer/todo-linter/issues/1): a short
// description
```

or:

```py
# TODO(chrish@pobox.com https://worktree.ca/taffer/todo-linter/issues/1): a short
# description
```

or:

```html
<!--
TODO(chrish@pobox.com https://worktree.ca/taffer/todo-linter/issues/1): a short
description
-->
```

The idea here is that future you, or someone else, will know where to get more
context for the task, so they can actually address it at some point. The linter
makes no attempt to verify the user email or the issue URL, so these can be
whatever makes sense for your project.

You can run `todo-linter` against any file, as long as it's valid UTF-8.

## To-do items

By default, `todo-linter` looks lines containing these tags:
`TODO`, `FIXME`, `XXX`, <!-- todo-linter: ignore -->
followed by a user identifier, space, and URL inside of parentheses.

You can adjust these with the `--delimiter`, `--issue-reference`, `--todo-tags`,
and `--user-identifier` arguments:

- `--delimiter` - Character to use as a delimiter between the user identifier
  and the issue reference. Defaults to space.
- `--issue-reference` - One of these values, such as `--issue-reference url`:
  - `number` - An issue number in your repo, such as `#14`. This is nice and
    short, but doesn't provide a clickable link like `url` does.
  - `other` - Free-form.
  - `unsafe-url` - Like `url` but for `http://hostname/path` type strings.
  - `url` - Matches `https://hostname/path` type strings.
- `--todo-tags` - A comma-separated list of to-do tags, such as
  `--todo-tags To-do` or
  `--todo-tags TODO,FIXME,XXX` <!-- todo-linter: ignore --> (the default).
- `--user-identifier` - One of these values, such as `--user-identifier email`:
  - `at-tag` - Matches `@user` type strings, frequently found in Discord,
    Mastodon, Mattermost, Slack, etc.
  - `bare` - Matches any `user`.
  - `email` - Matches `user@hostname` type strings. (Default)

Again, `todo-linter` doesn't validate issue references or user identifiers.

You can also set these in a
[`.todo-linter.toml` file](https://worktree.ca/taffer/todo-linter/src/branch/main/todo-linter.toml)
in the current directory (or anywhere is you use the `--config` argument).

### Ignoring problems

You can tell `todo-linter` to ignore an invalid to-do item by adding an inline
comment with `todo-linter: ignore`:

```c
// I don't want to correct my linter errors:
//
// TODO: I hate writing real TODO items. todo-linter: ignore
```

```py
# This one isn't actually an error:
#
# This is a big TODO. todo-linter: ignore
```

You can disable (and re-enable) the linter for larger blocks (or entire files)
using `todo-linter: disable` and <!-- todo-linter: ignore -->
`todo-linter: enable` comments: <!-- todo-linter: ignore -->

```py
# todo-linter: disable
#
# Any TODO, FIXME, XXX, etc. in this block will be ignored by the linter.
# You can put todo-linter: disable at the top of a file to exclude it entirely.
#
# Use this to reactivate the linter:
#
# todo-linter: enable
```

Because `todo-linter` isn't parsing your code at all, these can appear
anywhere in your comments (or even your code if that's your thing).

If it comes up, `todo-linter: ignore` takes precedent over `disable`/`enable`.

## Installation

If you're using `todo-linter` with pre-commit, you can skip this.

To install `todo-linter`, use `pipx` from your clone of the repo:

```sh
$ pipx install .
  installed package todo-linter 1.0.0, installed using Python 3.14.5
  These apps are now available
    - todo-linter
done! ✨ 🌟 ✨
```

### Using it with pre-commit

[`pre-commit`](https://pre-commit.com/) is handy, you should try it!

To use `todo-linter` with your project, add this `- repo` stanza to your
`.pre-commit-config.yaml`'s `repos:` section:

```yaml
repos:
  - repo: https://worktree.ca/taffer/todo-linter
    rev: {release}
    hooks:
      - id: todo-linter
```

Where `{release}` is the version tag you want to use, such as `v1.0` or a
commit hash.

## Credits

Repo icon by [Delapoutie](https://delapouite.com/) on
[game-icons.net](https://game-icons.net/1x1/delapouite/stabbed-note.html),
licensed under the
[Creative Commons BY 3.0](http://creativecommons.org/licenses/by/3.0/) license.

## License

`todo-linter` is Creative Commons BY-NC-SA 4.0; see [LICENSE.md](LICENSE.md) for
details.

No, you cannot train your LLM on this repo. Yes, I know you're going to ignore
that, you slop-generating scum.
