Run Linting and Formatting Workflow

Quick Start → Purpose | When to Use | Quick Start

Core Operations → Run Linting | Auto-Fix | Formatting

Configuration → Ruff Config | Violation Codes | Common Fixes

Workflows → Common Workflows | Output Interpretation | Integration

Help → Troubleshooting | Requirements

Purpose

Master ruff usage for linting (code quality) and formatting (code style) in temet. Understand when to check vs format, how to auto-fix violations, and interpret common error codes.

When to Use

Use this skill when:

•Running code quality checks before commits
•Fixing linting violations
•Formatting code to match project standards
•Understanding ruff error codes (F401, E501, etc.)
•Configuring ruff for project-specific rules

User trigger phrases:

•"run linting"
•"format code"
•"fix lint errors"
•"ruff check"
•"what does E501 mean?"

Quick Start

Most common workflows:

bash

# Check for lint violations (don't modify files)
ruff check src/ tests/

# Auto-fix violations (safe fixes only)
ruff check src/ tests/ --fix

# Format code (modifies files)
ruff format src/ tests/

# Check formatting without modifying
ruff format src/ tests/ --check

# Full workflow (lint + format)
ruff check src/ tests/ --fix && ruff format src/ tests/

Instructions

Understanding Ruff vs Other Tools

Ruff replaces multiple tools:

Tool	What It Did	Ruff Equivalent
`black`	Code formatting	`ruff format`
`isort`	Import sorting	`ruff check --select I`
`flake8`	Linting	`ruff check`
`pylint`	Linting	`ruff check`
`pyupgrade`	Python version upgrades	`ruff check --select UP`
`autoflake`	Remove unused imports	`ruff check --select F401 --fix`

Why ruff:

•⚡ 10-100x faster than other tools (written in Rust)
•🎯 One tool replaces 5-6 tools
•🔧 Auto-fix for most violations
•📝 Configurable (select/ignore rules)

Step 1: Run Linting (ruff check)

Basic usage:

bash

ruff check src/ tests/

Output (success):

code

All checks passed!

Output (with violations):

code

src/temet/core/event_bus.py:15:1: F401 [*] `logging` imported but unused
src/temet/core/event_bus.py:42:80: E501 Line too long (102 > 100)
src/temet/plugins/hooks/session_start/plugin.py:23:5: B008 Do not perform function call `dict` in argument defaults
Found 3 errors.
[*] 1 fixable with the `--fix` option.

Understanding output:

•File:line:col - Location of violation
•Code - Error code (e.g., F401, E501, B008)
•[*] - Fixable with --fix
•Message - Description of violation

Step 2: Auto-Fix Violations

Safe auto-fix (recommended):

bash

ruff check src/ tests/ --fix

What gets fixed:

•✅ Unused imports removed
•✅ Imports sorted (isort-compatible)
•✅ Unnecessary parentheses removed
•✅ Quoted strings normalized
•✅ Whitespace issues fixed
•⚠️ Does NOT fix: Complex violations requiring manual intervention

Check what would be fixed (dry-run):

bash

ruff check src/ tests/ --fix --diff

Unsafe fixes (use with caution):

bash

ruff check src/ tests/ --fix --unsafe-fixes

When to use:

•--fix: Before every commit (auto-fix safe issues)
•--fix --diff: Preview changes before applying
•--unsafe-fixes: Only when you understand the changes

Step 3: Run Formatting (ruff format)

Format files in-place:

bash

ruff format src/ tests/

Output:

code

3 files reformatted, 244 files left unchanged

Check formatting without modifying:

bash

ruff format src/ tests/ --check

Output (violations):

code

Would reformat: src/temet/core/event_bus.py
Would reformat: src/temet/plugins/hooks/session_start/plugin.py
2 files would be reformatted, 245 files left unchanged

See what would change (dry-run):

bash

ruff format src/ tests/ --diff

When to use:

•ruff format: Before commits (format all code)
•ruff format --check: In CI/CD (verify formatting)
•ruff format --diff: Review formatting changes

Step 4: Understand Ruff Configuration

temet ruff configuration (pyproject.toml):

toml

[tool.ruff]
line-length = 100  # Max line length
target-version = "py312"  # Python 3.12

[tool.ruff.lint]
select = ["ALL"]  # Enable ALL rules by default
ignore = [
    "D",        # pydocstyle (docstrings not enforced)
    "COM812",   # Trailing comma (conflicts with formatter)
    "ISC001",   # Single-line implicit concat (conflicts with formatter)
    "T201",     # print() allowed (CLI tool needs print)
    "BLE001",   # Catching Exception allowed (plugin error handling)
    "ARG001",   # Unused function args (test fixtures, protocols)
    "ARG002",   # Unused method args (test fixtures, protocols)
]

[tool.ruff.lint.per-file-ignores]
"tests/**/*.py" = [
    "S101",     # assert allowed in tests
    "ANN",      # Type annotations optional in tests
]

[tool.ruff.format]
quote-style = "double"  # Use " not '
indent-style = "space"  # 4 spaces (not tabs)

Key rules:

•Line length: 100 characters (not 80)
•Target: Python 3.12 (uses modern syntax)
•Quotes: Double quotes preferred
•Indentation: 4 spaces

Step 5: Common Violation Codes

Import-related (F):

Code	Description	Fix
F401	Imported but unused	`ruff check --fix` removes
F403	`from module import *`	Specify imports explicitly
F811	Redefined unused variable	Rename or remove duplicate

Code style (E/W):

Code	Description	Fix
E501	Line too long (> 100)	Break line or shorten
E711	Comparison to None should be `is`	Use `is None`
W291	Trailing whitespace	`ruff check --fix` removes

Best practices (B):

Code	Description	Fix
B008	Function call in argument defaults	Use `default_factory` or None
B006	Mutable default argument	Use `None` and create in function
B011	`assert False` instead of `raise`	Use `raise AssertionError`

Type checking (ANN):

Code	Description	Fix
ANN001	Missing type annotation (arg)	Add type annotation
ANN201	Missing return type	Add `-> ReturnType`
ANN401	`Any` type (too vague)	Use specific type

See: Ruff rule reference for complete list

Common Workflows

Workflow 1: Pre-Commit (Fix + Format)

bash

# Fix lint violations + format code
ruff check src/ tests/ --fix && ruff format src/ tests/

# Verify no violations remain
ruff check src/ tests/
ruff format src/ tests/ --check

Time: 1-2 seconds

Workflow 2: Development (Check Only)

bash

# Check for violations (don't modify files)
ruff check src/ tests/

# If violations: Fix manually or use --fix

Time: < 1 second

Workflow 3: CI/CD (Verify Only)

bash

# In CI pipeline: Verify linting and formatting
ruff check src/ tests/
ruff format src/ tests/ --check

# If violations: Fail CI (developer must fix locally)

Time: < 1 second (fast feedback)

Workflow 4: Format on Save (IDE Integration)

VSCode settings.json:

json

{
  "[python]": {
    "editor.defaultFormatter": "charliermarsh.ruff",
    "editor.formatOnSave": true,
    "editor.codeActionsOnSave": {
      "source.organizeImports": true,
      "source.fixAll": true
    }
  }
}

Result: Auto-fix + format on every file save

Interpreting Lint Output

Example Output

code

src/temet/core/event_bus.py:15:1: F401 [*] `logging` imported but unused
src/temet/core/event_bus.py:42:80: E501 Line too long (102 > 100)
src/temet/core/event_bus.py:67:5: B006 [*] Do not use mutable data structures for argument defaults
src/temet/plugins/hooks/session_start/plugin.py:23:10: ANN001 Missing type annotation for function argument `event`
Found 4 errors.
[*] 2 fixable with the `--fix` option.

Breakdown:

•F401 - Unused import (fixable) → ruff check --fix
•E501 - Line too long → Break line manually
•B006 - Mutable default (fixable) → ruff check --fix
•ANN001 - Missing annotation → Add type manually

Action plan:

bash

# 1. Auto-fix what's possible
ruff check src/ tests/ --fix

# 2. Manually fix remaining issues
# - E501: Break long line
# - ANN001: Add type annotation

# 3. Verify all fixed
ruff check src/ tests/

Fixing Common Violations

Violation 1: F401 - Unused Import

Error:

code

src/temet/core/event_bus.py:15:1: F401 [*] `logging` imported but unused

Fix (auto):

bash

ruff check src/ tests/ --fix

Or manually:

python

# ❌ Before
import logging  # Unused
from typing import Any

# ✅ After
from typing import Any  # Removed unused import

Violation 2: E501 - Line Too Long

Error:

code

src/temet/core/event_bus.py:42:80: E501 Line too long (102 > 100)

Fix (manual):

python

# ❌ Before (102 characters)
def process_event(event: Event, handlers: list[Callable], config: dict[str, Any]) -> dict[str, Any]:

# ✅ After (break line)
def process_event(
    event: Event,
    handlers: list[Callable],
    config: dict[str, Any],
) -> dict[str, Any]:

Violation 3: B006 - Mutable Default Argument

Error:

code

src/temet/core/event_bus.py:67:5: B006 [*] Do not use mutable data structures for argument defaults

Fix (auto or manual):

python

# ❌ Before (dangerous - shared mutable default)
def process(data: dict[str, Any] = {}):
    data["key"] = "value"  # Modifies shared default!

# ✅ After (safe - create new dict each call)
def process(data: dict[str, Any] | None = None):
    if data is None:
        data = {}
    data["key"] = "value"

Violation 4: ANN001 - Missing Type Annotation

Error:

code

src/temet/plugins/hooks/session_start/plugin.py:23:10: ANN001 Missing type annotation for function argument `event`

Fix (manual):

python

# ❌ Before
def handle(self, event):
    return event.data

# ✅ After
def handle(self, event: Event) -> dict[str, Any]:
    return event.data

Integration with Other Skills

Before linting:

•setup-temet-project - Ensure ruff installed
•run-type-checking-workflow - Fix type errors first (easier to lint)

After linting:

•run-quality-gates - Run all gates (includes ruff)
•git-commit-push - Lint passes as pre-commit requirement

During development:

•interpret-check-all-output - Understand check_all.sh results (includes ruff)

Troubleshooting

Issue: `ruff: command not found`

Solution:

bash

# Use uv run prefix
uv run ruff check src/ tests/

# Or ensure ruff installed
uv pip install -e ".[dev]"

Issue: Too many violations to fix manually

Solution:

bash

# Auto-fix everything possible
ruff check src/ tests/ --fix

# Then fix remaining violations one file at a time
ruff check src/temet/core/event_bus.py --fix

Issue: Conflict between ruff and pyright

Symptoms: Ruff suggests one fix, pyright suggests another

Solution:

bash

# 1. Fix pyright errors first (type safety)
pyright src/ tests/

# 2. Then run ruff (code style)
ruff check src/ tests/ --fix

Rationale: Type safety > code style. Fix types first, style second.

Issue: `--fix` breaks code

Symptoms: Auto-fix changes behavior or introduces bugs

Solution:

bash

# 1. Review changes before applying
ruff check src/ tests/ --fix --diff

# 2. If looks wrong, skip auto-fix
# 3. Fix manually with understanding

# 4. If auto-fix is wrong, report bug to ruff
# (Rare - ruff is well-tested)

Issue: Want to ignore specific violation

Solution (per-line ignore):

python

# Ignore specific rule on one line
result = some_call()  # noqa: E501

Solution (file-level ignore):

toml

# In pyproject.toml
[tool.ruff.lint.per-file-ignores]
"src/temet/legacy/*.py" = ["E501", "F401"]  # Ignore in legacy code

Rule: Only ignore with justification comment:

python

# noqa: E501 - API URL cannot be broken
api_url = "https://very-long-api-url.example.com/v1/endpoint/with/many/parameters"

Requirements

Dependencies (auto-installed with [dev]):

•ruff - Linter and formatter

Configuration files:

•pyproject.toml - Ruff configuration (required)
•.vscode/settings.json - IDE integration (optional)

No manual installation needed - included in pyproject.toml.

Expected Output

Success (No Violations)

bash

$ ruff check src/ tests/
All checks passed!

$ ruff format src/ tests/ --check
247 files already formatted

✅ Ready to commit

Violations Found

bash

$ ruff check src/ tests/
src/temet/core/event_bus.py:15:1: F401 [*] `logging` imported but unused
src/temet/core/event_bus.py:42:80: E501 Line too long (102 > 100)
Found 2 errors.
[*] 1 fixable with the `--fix` option.

$ ruff format src/ tests/ --check
Would reformat: src/temet/core/event_bus.py
1 file would be reformatted, 246 files left unchanged

🔧 Fix with:

bash

ruff check src/ tests/ --fix && ruff format src/ tests/

quality-run-linting-formatting

Run Linting and Formatting Workflow

Table of Contents

Purpose

When to Use

Quick Start

Instructions

Understanding Ruff vs Other Tools

Step 1: Run Linting (ruff check)

Step 2: Auto-Fix Violations

Step 3: Run Formatting (ruff format)

Step 4: Understand Ruff Configuration

Step 5: Common Violation Codes

Common Workflows

Workflow 1: Pre-Commit (Fix + Format)

Workflow 2: Development (Check Only)

Workflow 3: CI/CD (Verify Only)

Workflow 4: Format on Save (IDE Integration)

Interpreting Lint Output

Example Output

Fixing Common Violations

Violation 1: F401 - Unused Import

Violation 2: E501 - Line Too Long

Violation 3: B006 - Mutable Default Argument

Violation 4: ANN001 - Missing Type Annotation

Integration with Other Skills

Troubleshooting

Issue: `ruff: command not found`

Issue: Too many violations to fix manually

Issue: Conflict between ruff and pyright

Issue: `--fix` breaks code

Issue: Want to ignore specific violation

Requirements

Expected Output

Success (No Violations)

Violations Found

Run Linting and Formatting Workflow

Table of Contents

Purpose

When to Use

Quick Start

Instructions

Understanding Ruff vs Other Tools

Step 1: Run Linting (ruff check)

Step 2: Auto-Fix Violations

Step 3: Run Formatting (ruff format)

Step 4: Understand Ruff Configuration

Step 5: Common Violation Codes

Common Workflows

Workflow 1: Pre-Commit (Fix + Format)

Workflow 2: Development (Check Only)

Workflow 3: CI/CD (Verify Only)

Workflow 4: Format on Save (IDE Integration)

Interpreting Lint Output

Example Output

Fixing Common Violations

Violation 1: F401 - Unused Import

Violation 2: E501 - Line Too Long

Violation 3: B006 - Mutable Default Argument

Violation 4: ANN001 - Missing Type Annotation

Integration with Other Skills

Troubleshooting

Issue: ruff: command not found

Issue: Too many violations to fix manually

Issue: Conflict between ruff and pyright

Issue: --fix breaks code

Issue: Want to ignore specific violation

Requirements

Expected Output

Success (No Violations)

Violations Found

Issue: `ruff: command not found`

Issue: `--fix` breaks code