---
name: lint
description: >
  Run ruff lint checks on piker Python files for
  docstring style (D2xx) and code convention
  compliance. Checks staged files by default.
user-invocable: true
argument-hint: "[--all|--fix|--stats|paths...]"
allowed-tools: Bash(python3 *), Bash(ruff *), Read, Edit
---

# Ruff Lint Checker

Run piker's ruff config against staged files,
specific paths, or the full codebase.

## Available scripts

- **`scripts/check.py`** — self-contained (PEP 723)
  wrapper around `ruff check` that defaults to staged
  files and uses the project's `ruff.toml`.

## Usage

```bash
# check staged Python files (default)
python3 scripts/check.py

# check full codebase
python3 scripts/check.py --all

# auto-fix fixable violations
python3 scripts/check.py --fix

# preview fixes without applying
python3 scripts/check.py --diff

# show per-rule violation counts
python3 scripts/check.py --stats

# check specific files
python3 scripts/check.py piker/ui/_style.py
```

## Common violations

| Rule | Meaning | Fixable? |
|------|---------|----------|
| D213 | summary not on 2nd line after `'''` | yes |
| D205 | no blank line after summary | no |
| D204 | no blank line after class docstring | yes |
| D209 | closing quotes not on own line | yes |
| D200 | ignored — piker always multiline | n/a |
| W291 | trailing whitespace | yes |

## Fixing D213 (most common)

Convert this:
```python
"""Summary on first line."""
```

To piker's `'''` multiline style:
```python
'''
Summary on second line.

'''
```

For D205, insert a blank line between the summary
and description paragraphs inside the docstring.