Metadata-Version: 2.5
Name: python-constricter
Version: 0.4.4
Import-Name: constricter
Summary: Lint rules: every local variable is typed where it's first bound. A flake8 plugin, a pylint plugin and a standalone CLI.
Author: Ivy Duggan
License-Expression: MIT
License-File: LICENSE.md
Classifier: Framework :: Flake8
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
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: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Typing :: Typed
Requires-Python: >=3.11
Provides-Extra: flake8
Requires-Dist: flake8>=7; extra == 'flake8'
Provides-Extra: pylint
Requires-Dist: pylint>=3; extra == 'pylint'
Description-Content-Type: text/markdown

# python-con`strict`er

> EXPERIMENTAL UNTIL v1.0.0

**I want all of my python code typed.**

[![CI](https://github.com/ivylikethevine/python-constricter/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/ivylikethevine/python-constricter/actions/workflows/ci.yml)
[![Security](https://github.com/ivylikethevine/python-constricter/actions/workflows/security.yml/badge.svg?branch=main)](https://github.com/ivylikethevine/python-constricter/actions/workflows/security.yml)
[![PyPI](https://img.shields.io/pypi/v/python-constricter)](https://pypi.org/project/python-constricter/)
[![Python](https://img.shields.io/pypi/pyversions/python-constricter)](https://pypi.org/project/python-constricter/)
[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/ivylikethevine/python-constricter/badge)](https://scorecard.dev/viewer/?uri=github.com/ivylikethevine/python-constricter)
[![Test coverage: 100%](https://img.shields.io/badge/test_coverage-100%25-brightgreen)](pyproject.toml)
[![Annotations: 100%](https://img.shields.io/badge/annotations-100%25-brightgreen)](#annotation-coverage)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE.md)

Lint rules: every local variable is typed where it's first bound. Ships as a flake8 plugin, a pylint
plugin and a standalone command (for ruff, which loads no plugins).

```text
            /^\/^\
          _|__|  O|
\/     /~     \_/ \
  \____|__________/  \
        \_______      \
                `\     \                 \
                  |     |                  \
                  /      /                    \
                /     /                       \\
              /      /                         \ \
              /     /                            \  \
            /     /             _----_            \   \
          /     /           _-~      ~-_         |   |
          (      (        _-~    _--_    ~-_     _/   |
          \      ~-____-~    _-~    ~-_    ~-_-~    /
            ~-_           _-~          ~-_       _-~
                ~--______-~                ~-___-~
```

---

```python
def total(items: list[int]) -> int:
    count = 0  # LVA001
    result: int = 0  # ok
    first, *rest = items  # LVA001 twice
    head: int
    tail: list[int]
    head, *tail = items  # ok: declared first
    if (n := len(items)) > 3:  # LVA001
        result = n  # ok: rebinding
    for item in items:  # LVA002
        result += item
    for other in items:  # type: int  # LVA003
        result += other
    value: int
    for value in items:  # ok: declared first
        result += value
    return result
```

## Rules

Checked per function body, including methods and nested functions; with `all-scopes`, module and
class bodies too. Statements are read in source order, and only a name's first binding counts
(`LVA008`–`LVA010` aside, which read every one).

| Code     | Reports                                                                                   | Fix                                            |
| -------- | ----------------------------------------------------------------------------------------- | ---------------------------------------------- |
| `LVA001` | `=`, unpacking, `:=` or `with ... as` in a function without annotation                    | `name: T = ...`, or `name: T` first            |
| `LVA002` | an untyped `for` target or `match` capture                                                | `name: T` first (or a type comment)            |
| `LVA003` | a `for` target typed only by `# type: T`                                                  | `name: T` first                                |
| `LVA004` | with `all-scopes`: the same as `LVA001`, in a module or class body                        | `name: T = ...` (`ClassVar[T]` in a dataclass) |
| `LVA005` | an annotation with `Any`, `object` or a generic without its parameters, past `vague`      | name the real type                             |
| `LVA006` | an annotation nested `nesting` deep (3 by default)                                        | a `type` alias for a part of it                |
| `LVA007` | a name annotated again with the type it already has, in the same block                    | drop the second annotation                     |
| `LVA008` | with every value the name ever holds known: an annotation that could narrow to them       | narrow it (`total: int`)                       |
| `LVA009` | a value, anywhere in the name's lifetime, whose type doesn't fit its annotation           | fix the value, or widen the annotation         |
| `LVA010` | with every value known: a union member no value is                                        | drop the member                                |
| `LVA011` | an annotation listing a fixed-length tuple of more than `max-length` types (4 by default) | name the fields (a `NamedTuple`, a dataclass)  |
| `LVA012` | opt-in: a local bound once, outside any loop, and never rebound                           | `name: Final = ...`                            |
| `LVA013` | opt-in: an instance attribute a plain class's method first stores, declared nowhere in it | `self.x: T = ...`                              |
| `LVA014` | opt-in: a plain function that declares no return type                                     | `def f(...) -> T:`                             |
| `LVA015` | opt-in: a parameter with no annotation                                                    | `def f(x: T):`                                 |

Exempt: comprehensions, `except ... as`, imports, `def`/`class`, `type` aliases, parameters,
`global`/`nonlocal`, and `_`; in module and class bodies, dunder names (`__all__`, `__slots__`) and
enum members (a base imported from `enum`, however it's aliased, or else whose name ends in `Enum`
or `Flag`). And what makes a type, not a value, which an annotation would turn into a variable to a
type checker: `T = TypeVar("T")`, a `ParamSpec`, a `TypeVarTuple`, a `NewType`, and a functional
`NamedTuple`, `TypedDict`, `Enum` or `collections.namedtuple`, however `typing`,
`typing_extensions`, `enum` or `collections` is imported.

A `# type:` comment (`x = 1  # type: int`, `with f() as x:  # type: T`) counts as an annotation with
`type-comments`, or automatically in a module written to run on Python 2: one that imports
`print_function`, `unicode_literals`, `absolute_import`, `division`, `with_statement`, `generators`
or `nested_scopes` from `__future__`. Otherwise it's `LVA001`, and `--fix` writes the comment's type
as the annotation and drops the comment.

`LVA007` compares a block on its own: an `if`'s body and its `orelse`, a `try`'s body and its
`except`s, and the like, are different blocks, since they don't both run in the same pass.

`LVA009` checks every binding of an annotated name (or parameter) in the scope, wherever and in
whatever order they run, but only one whose value's type `--fix` would infer with certainty, and
only against types whose every subclass is known: builtins, and classes the module defines on such
bases. An imported class, a protocol or an alias is never compared, builtin containers are compared
by the container alone (`flags: tuple[str, ...] = ("-q",)` fits), a copy of a union-typed name is
skipped (an `is None` check may have narrowed it), and so is a name annotated only under
`if TYPE_CHECKING:`. It has no `--fix`.

`LVA008` and `LVA010` also need every binding's value known (one unknown call, loop target or
unpacking and the name could hold anything), and are only claimed for a function's own names: a
module or class variable is state other code rebinds out of sight (`mod.X = ...`, `self.x = ...`,
`monkeypatch`), and a `nonlocal` write from a nested function counts as unknown too. Neither has a
`--fix`: `--fix` adds annotations, it doesn't rewrite them.

## Levels

Each level makes one more code an error. The rest are warnings: the CLI prints them (as `::warning`
or SARIF `warning` in those formats) but exits 0; flake8 and pylint report errors only.

| Level             | Errors                                 | Warnings                                                  |
| ----------------- | -------------------------------------- | --------------------------------------------------------- |
| `relaxed` / `0`   | none                                   | `LVA001`–`LVA004`, `LVA007`, `LVA009`                     |
| `strict` / `1`    | `LVA001`, `LVA004` (the default)       | `LVA002`, `LVA003`, `LVA005`–`LVA007`, `LVA009`, `LVA011` |
| `constrict` / `2` | `LVA001`, `LVA004`, `LVA002`, `LVA009` | `LVA003`, `LVA005`–`LVA008`, `LVA010`, `LVA011`           |
| `suffocate` / `3` | all                                    | none                                                      |

`LVA005`, `LVA006` and `LVA011` aren't reported at `relaxed`; `LVA008` and `LVA010` only from
`constrict`. `LVA012` is opt-in, reported only when selected by its full code
(`--extend-select LVA012`, flake8's `extend-select = LVA012`, pylint's `enable = could-be-final`),
at every level, and an error only at `suffocate`: on the corpus, 45–70% of every codebase's first
bindings qualify, so it suits a codebase that wants `Final` everywhere it can go, not a default.

`LVA013` is opt-in the same way (pylint's `enable = unannotated-instance-attribute`), and an error
from `strict`, as `LVA001` is. It reports an instance attribute a plain class's method stores
(`self.count = 0`) that no annotation in the class declares, at its first plain `self.x = value`:
a class the module defines once, with no keyword (a metaclass), on no base but `object` or another
such class, since another file's base may declare the attribute itself. Dunders, stores in a
nested function, and names the class's body or a base of the module's binds are left out.

`LVA014` is opt-in too (pylint's `enable = missing-return-type`), an error from `strict`. It
reports a plain function or method (not decorated) with no return annotation, as ruff's `ANN201`
does; its fix is what the function's own `return`s give (`-> int`, a method's a guess, as is a
function's whose `return`s' values are guessed), or `-> None` for one that returns nothing, or what
a traced run saw it return (`--infer-from`, a guess), where the type names only what the module
already binds. `LVA015` is opt-in the same way (pylint's
`enable = missing-parameter-type`): a parameter with no annotation, as ruff's `ANN001` reports it,
but a method's receiver; its fix, a guess, is what typed the parameter for the function's own
check: what every call passes it, the one class with every member the function reads of it, its
pytest fixture's value, or the one type the checked files annotate its name with. A signature is
written whole or not at all: a return on bare parameters, or one parameter's type among bare ones,
is an error to a checker held to complete signatures where none was. A signature `--fix` writes
reaches the other files in the same run.

Python 3.11+, no runtime dependencies.

## Use

| Tool   | Setup                                                 | Reports                         | Suppress                                         |
| ------ | ----------------------------------------------------- | ------------------------------- | ------------------------------------------------ |
| CLI    | `constricter [PATH...] [--level L] [--format F] [-q]` | `LVA001`–`LVA015`               | `# noqa: LVA001`                                 |
| flake8 | install it (on by default)                            | `LVA001`–`LVA015`               | `# noqa: LVA001`                                 |
| pylint | `load-plugins = ["constricter.plugins.pylint"]`       | `C9101`–`C9115` (symbols below) | `# noqa: LVA001` or `# pylint: disable=<symbol>` |
| ruff   | run the CLI after ruff; set `lint.external = ["LVA"]` | `LVA001`–`LVA015`               | `# noqa: LVA001`                                 |

pylint symbols: `unannotated-local-variable`, `untyped-for-or-match-variable`,
`comment-typed-for-variable`, `unannotated-module-or-class-variable`, `vague-annotation`,
`deeply-nested-annotation`, `redundant-annotation`, `narrowable-annotation`,
`mismatched-value-type`, `unused-union-member`, `long-tuple-annotation`, and, off until enabled,
`could-be-final`, `unannotated-instance-attribute`, `missing-return-type` and
`missing-parameter-type`.

Options:

| Option           | CLI                                                                                                                                                                                                                                                                                                                        | `[tool.constricter]`                            | flake8 (CLI or config)          | pylint                            |
| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- | ------------------------------- | --------------------------------- |
| level            | `--level`                                                                                                                                                                                                                                                                                                                  | `level`                                         | `--constricter-level`           | `constricter-level`               |
| strictest        | `--max`: `--level=suffocate` for every path, `--all-scopes`, and the opt-in `LVA012` and `LVA013`                                                                                                                                                                                                                          | —                                               | —                               | —                                 |
| every fix        | `--max-fix`: `--max`, `--fix --unsafe-fixes`, and `--infer-with` each of basedpyright, ty and pyrefly that's installed and runs                                                                                                                                                                                            | —                                               | —                               | —                                 |
| type comments    | `--type-comments`                                                                                                                                                                                                                                                                                                          | `type-comments`                                 | `--constricter-type-comments`   | `constricter-type-comments = yes` |
| all scopes       | `--all-scopes`                                                                                                                                                                                                                                                                                                             | `all-scopes`                                    | `--constricter-all-scopes`      | `constricter-all-scopes = yes`    |
| nesting          | `--nesting N`                                                                                                                                                                                                                                                                                                              | `nesting`                                       | `--constricter-nesting`         | `constricter-nesting`             |
| max length       | `--max-length N` (LVA011)                                                                                                                                                                                                                                                                                                  | `max-length`                                    | `--constricter-max-length`      | `constricter-max-length`          |
| vague            | `--vague LEVEL` (LVA005, and the fixes offered): -1 none (the default), 0 one `Any` inside a type that says the rest (`tuple[str, Any]`), N from 1 N + 1, or one alone                                                                                                                                                     | `vague`                                         | `--constricter-vague`           | `constricter-vague`               |
| min python       | `--min-python VERSION` (the oldest Python the code runs on, whose syntax `--fix` writes; default: `requires-python`'s)                                                                                                                                                                                                     | `min-python`                                    | -                               | -                                 |
| type hierarchy   | -                                                                                                                                                                                                                                                                                                                          | `narrower` (a table)                            | `--constricter-narrower`        | `constricter-narrower`            |
| fix              | `--fix` (`--unsafe-fixes` for guesses, `--likely` for those measured to hold), `--diff` to preview                                                                                                                                                                                                                         | -                                               | -                               | -                                 |
| infer with       | `--infer-with CHECKERS` (`basedpyright`, `ty`, `pyrefly`, several: inferred types, as guesses)                                                                                                                                                                                                                             | `infer-with`                                    | -                               | -                                 |
| infer from       | `--infer-from FILE` (the types `python -m constricter.trace -m pytest` recorded from a run, as guesses)                                                                                                                                                                                                                    | `infer-from`                                    | -                               | -                                 |
| show fixes       | `--show-fixes` (each fix and how it was decided; with `--fix`, those made too)                                                                                                                                                                                                                                             | -                                               | -                               | -                                 |
| fix levels       | `--fix-select`, `--fix-ignore`, `--unsafe-fix-select` (mechanisms: [docs/FIXES.md](https://github.com/ivylikethevine/python-constricter/blob/main/docs/FIXES.md#fix-levels))                                                                                                                                               | `fix-select`, `fix-ignore`, `unsafe-fix-select` | -                               | -                                 |
| fix plain bases  | `--fix-plain-bases BASES` (frameworks' classes whose subclasses' bodies `--fix` annotates; django's are built in)                                                                                                                                                                                                          | `fix-plain-bases`                               | -                               | -                                 |
| fix widen        | `--fix-widen KINDS` (wider types `--fix` may write, each marked: `untyped-parameters`, `empty-containers`, `mixed-containers`, `unions`, `vague`, `untyped-calls`, `unknown-calls`; `all`: every one; [docs/FIXES.md](https://github.com/ivylikethevine/python-constricter/blob/main/docs/FIXES.md#wider-types-fix-widen)) | `fix-widen`                                     | -                               | -                                 |
| select           | `--select CODES` (codes or prefixes)                                                                                                                                                                                                                                                                                       | `select`                                        | flake8's own `select`           | pylint's own `enable`             |
| extend select    | `--extend-select CODES` (also report these; an opt-in code by its full code)                                                                                                                                                                                                                                               | `extend-select`                                 | flake8's own `extend-select`    | pylint's own `enable`             |
| ignore           | `--ignore CODES`                                                                                                                                                                                                                                                                                                           | `ignore`                                        | flake8's own `extend-ignore`    | pylint's own `disable`            |
| exclude          | `--exclude GLOB` (repeatable)                                                                                                                                                                                                                                                                                              | `exclude`                                       | flake8's own `exclude`          | pylint's own `ignore-paths`       |
| format           | `--format`: `text`, `full` (with source), `json`, `github`, `sarif`, `gitlab`, `junit`, `rdjson`                                                                                                                                                                                                                           | -                                               | -                               | -                                 |
| statistics       | `--statistics` (counts per code, text format)                                                                                                                                                                                                                                                                              | -                                               | -                               | -                                 |
| jobs             | `--jobs N` (`-j`; 0: one per CPU)                                                                                                                                                                                                                                                                                          | `jobs`                                          | flake8's own `--jobs`           | pylint's own `--jobs`             |
| baseline         | `--baseline FILE`; `--write-baseline` records it                                                                                                                                                                                                                                                                           | `baseline`                                      | -                               | -                                 |
| coverage         | `--coverage`, `--fail-under PCT`                                                                                                                                                                                                                                                                                           | -                                               | -                               | -                                 |
| per-path levels  | -                                                                                                                                                                                                                                                                                                                          | `per-path-levels`                               | -                               | -                                 |
| per-file ignores | -                                                                                                                                                                                                                                                                                                                          | `per-file-ignores`                              | flake8's own `per-file-ignores` | -                                 |
| stdin            | `-` as the path, `--stdin-filename PATH`                                                                                                                                                                                                                                                                                   | -                                               | flake8's own `-`                | -                                 |
| exit status      | `--exit-zero`                                                                                                                                                                                                                                                                                                              | -                                               | flake8's own `--exit-zero`      | pylint's own `--exit-zero`        |
| output file      | `--output-file FILE`                                                                                                                                                                                                                                                                                                       | -                                               | flake8's own `--output-file`    | pylint's own `--output`           |

`constricter --explain LVA002` prints a code's rationale, its fix, and the levels that report it.

The CLI reads `[tool.constricter]` from the nearest `pyproject.toml` above the current directory;
its flags override it, and `--exclude` adds to it. An unknown key or a bad value exits 2.

```toml
[tool.constricter]
level = "constrict" # or 2
exclude = ["tests/fixtures/*"]
type-comments = false
all-scopes = true
nesting = 3
max-length = 4
vague = -1 # the default: no `Any`; 0 lets `dict[str, Any]` through, 1 `Any` itself
min-python = "3.11" # the default: your `requires-python`'s lower bound
jobs = 0
baseline = "constricter-baseline.json" # the default; relative to this pyproject.toml

# The first glob a file matches sets its level; other files get `level`.
[tool.constricter.per-path-levels]
"tests/*" = "strict"

# Codes (or prefixes) to drop for files matching a glob.
[tool.constricter.per-file-ignores]
"tests/fixtures/*" = ["LVA005", "LVA006"]

# Your own type hierarchy for LVA008–LVA010: each type, and the types it's narrower than.
[tool.constricter.narrower]
UserId = ["str"]  # an imported NewType the rules then compare
int = []          # an `int` no longer fits `float`
select = ["LVA00"]
ignore = ["LVA003"]
```

`--fix` adds the annotation where the value decides it: a literal (`count = 0` becomes
`count: int = 0`), a container whose elements agree, a constructor or a function that declares its
return type or whose `return`s agree (in another checked file too), a copy, subscript, attribute or
method call of a local whose type is known, and values computed from those; a loop's target or an
unpacking's names get a declaration on the line before. `--unsafe-fixes` adds guesses, `--likely`
only those measured to hold as often as a certain fix
([docs/LIKELY.md](https://github.com/ivylikethevine/python-constricter/blob/main/docs/LIKELY.md)),
and `--show-fixes` lists each fix and how its value decided it, and after `--fix` each one made.
`--infer-with basedpyright` (or `ty`, or `pyrefly`, or several: `basedpyright,ty`; each installed
alongside) asks those type checkers for what `--fix` can't type itself, as guesses;
`--infer-from FILE` takes the types a run bound each name to, recorded by
`python -m constricter.trace -m pytest`, the same way. The full list is in
[docs/FIXES.md](https://github.com/ivylikethevine/python-constricter/blob/main/docs/FIXES.md).

### Installing and running

```bash
pip install python-constricter           # into the project's environment
uvx --from python-constricter constricter # or run it without installing: uv's tool runner
pipx run --spec python-constricter constricter  # or pipx's
```

On CPython 3.11 to 3.14 for Linux, macOS and Windows, pip installs a build compiled with mypyc,
about a fifth faster; anywhere else, the pure Python one, which finds and fixes the same.

Tools that run flake8 or pylint (VS Code's extensions, python-lsp-server, prospector, MegaLinter,
Trunk) pick the plugin up once it's installed alongside them.

Without `lint.external`, ruff flags `# noqa: LVA00x` (RUF102) and `--fix` deletes it.

The CLI defaults to `.`, checks `*.py` and `*.ipynb`, and skips hidden dirs, `__pycache__`, `venv`,
`site-packages`, `build`, `dist` and `node_modules` by directory name; `--exclude` adds more
directory names (or globs) to skip the same way, on top of matching whole paths and file names.
Under a directory in a git checkout it checks only what git tracks or would, so nothing a
`.gitignore` names (a file named on the command line is checked regardless); `--no-gitignore`, or
`gitignore = false`, walks the directory whole. Exit codes: `0` no errors, `1` errors, `2` an
unreadable or unparsable file, a `--fix` its encoding can't hold, or a bad `pyproject.toml`. A
module is read in its PEP 263 declaration's encoding.

pre-commit, after ruff's hooks (or `constricter-fix`, which runs `--fix` first):

```yaml
- repo: https://github.com/ivylikethevine/python-constricter
  rev: vX.Y.Z # the latest release; `pre-commit autoupdate` sets it
  hooks:
    - id: constricter
```

pre-commit.ci, tox, nox, Bazel, Pants and the GitHub Action (PR annotations, a summary table and a
SARIF log) are in
[docs/INTEGRATIONS.md](https://github.com/ivylikethevine/python-constricter/blob/main/docs/INTEGRATIONS.md);
settings for VS Code, Zed and Neovim are in
[docs/editors/](https://github.com/ivylikethevine/python-constricter/blob/main/docs/editors/README.md).

### Baselines

To adopt constricter on a codebase that already has offences, record them, then report only new
ones:

```bash
constricter --write-baseline src # writes constricter-baseline.json next to pyproject.toml
constricter src                  # reports only offences the baseline doesn't cover
```

A baseline counts each file's offences by code and variable name, not line number, so it survives
code moving around; another offence for a name it covers is still reported. Paths in it are relative
to it. It's JSON, and like every JSON file constricter reads it may have `//` and `/* */` comments
and trailing commas. `--baseline FILE` or `baseline` in `[tool.constricter]` names another file; the
default one is used only if it exists.

### Annotation coverage

`constricter --coverage src` prints the share of first bindings that are typed, per file and in
total; the bindings are the ones the rules cover (with `--all-scopes`, module and class bodies too),
and `# noqa` doesn't make one typed. `--fail-under PCT` (which implies `--coverage`) exits 1 below
PCT, so CI can hold a codebase to a share. With `--format=json` it prints
`{"typed", "total", "widened", "percent", "files"}`, which a badge can read: publish that JSON
somewhere (a gist, a release asset) and point
[shields.io's dynamic JSON badge](https://shields.io/badges/dynamic-json-badge) at it with the query
`$.percent`. This project keeps its own share at 100% in CI, so its badge is static.

### Notebooks

`.ipynb` files are checked too (directories include them): their code cells are read as one module,
IPython-only lines (`%magic`, `!shell`, `obj?`, `%%cell` magics) are skipped, and each offence is
reported at its cell and line (`analysis.ipynb:cell 3:2:5`). JSON output has a `cell` field; GitHub
and SARIF output point at the file and put the cell in the message. `--fix` and `--diff` edit the
cells, keeping the notebook's formatting.

### Adopting it on an existing codebase

1. See the scale: `constricter --statistics src` counts offences per code.
2. Record them: `constricter --write-baseline src`, and commit `constricter-baseline.json`.
3. Enforce it for new code: add the pre-commit hook or the GitHub Action; the baseline keeps old
   offences quiet, and `--diff` / `--fix` clear the easy ones.
4. Burn it down: fix a file or package at a time, then `--write-baseline` again to shrink the file.
5. Tighten: raise `level` (or `per-path-levels` for the parts that are clean), then turn on
   `all-scopes`.

### Output formats

`--format` is `text` (the default), `json`, `github` (workflow annotations), `sarif` (below),
`gitlab` (Code Climate JSON, for GitLab's merge-request Code Quality widget: pass the file as a
`codequality` report artifact), `junit` (a test suite per file, a failed test case per offence, for
Jenkins, Azure Pipelines, CircleCI or GitLab's test reports) or `rdjson` (for
[reviewdog](https://github.com/reviewdog/reviewdog), with each certain fix as a suggestion).
`--output-file FILE` writes the report there, and `--exit-zero` exits 0 even when there are errors
(not when a file can't be read).

### Editors (standard input)

`constricter - --stdin-filename path/to/file.py` checks standard input, reported as that path (which
also picks its per-path level and baseline entry; a `.ipynb` name reads a notebook). With `--fix` it
prints the fixed source instead of a report, and `--diff` diffs it. That's what editors that lint
unsaved buffers through a command need (none-ls, nvim-lint, flycheck, ALE, efm-langserver, Helix).

### SARIF (code scanning)

`--format=sarif` writes SARIF 2.1.0, with each result's level (`error` or `warning`) set by
`--level`. Each rule has its help text and a link to [Rules](#rules), and each certain fix is a
SARIF fix (columns count characters: `columnKind` is `unicodeCodePoints`). In GitHub Actions, upload
it to code scanning (the job needs `security-events: write`; the
[GitHub Action](https://github.com/ivylikethevine/python-constricter/blob/main/docs/INTEGRATIONS.md#github-actions)'s
`sarif-file` output does the same):

```yaml
- run: constricter --format=sarif src > constricter.sarif
- if: ${{ !cancelled() }} # upload the findings even when the step above failed on them
  uses: github/codeql-action/upload-sarif@6f2ac81f5cd81fe351a197ba0b00d91d03cd2aee # v4.39.0
  with:
    sarif_file: constricter.sarif
    category: constricter
```

SonarQube and SonarCloud import it with `sonar.sarifReportPaths=constricter.sarif`; any other tool
that reads SARIF 2.1.0 takes the same file.

## Development

Setting up, the checks CI runs, the corpus runs and the rules this project's own linters leave off
are in
[docs/CONTRIBUTING.md](https://github.com/ivylikethevine/python-constricter/blob/main/docs/CONTRIBUTING.md).

## Roadmap

What's next, by size:
[docs/ROADMAP.md](https://github.com/ivylikethevine/python-constricter/blob/main/docs/ROADMAP.md).
What's done, by scope:
[docs/COMPLETED.md](https://github.com/ivylikethevine/python-constricter/blob/main/docs/COMPLETED.md).

## AI usage

Heavily inspired by
[Dictionarry/Profilarr's AI Transparency Statement](https://v2.dictionarry.dev/ai-transparency).

I have used generative AI to write large parts of this code. All of the code here is my
_responsibility_ regardless: AI is a tool, not an owner of a project. I have personally understood,
reviewed, and approved all of the AI-generated code in this repository, and **mainline releases**
carry the same accountability to me as anything I write and publish myself.
