lint

# Linting and Code Quality Skill

This skill helps you efficiently validate and format code using the project's comprehensive linting infrastructure.

## When to Use This Skill

Use this skill when you:
- Edit a file and want to format it before committing
- Need to validate code style, types, or security
- Want to check for spelling errors or documentation issues
- Need to validate test infrastructure (suitespec, log messages)
- Want to run comprehensive quality checks before pushing

## Key Principles

1. **Always format after editing** - Use `hatch run lint:fmt -- <file>` immediately after code changes
2. **Run comprehensive checks before committing** - Use `hatch run lint:checks` before pushing
3. **Target specific files** - Use `-- <file>` syntax to validate only what you changed, not the entire codebase
4. **Fix auto-fixable issues** - Use `fmt` instead of manually fixing style issues
5. **Type check after adding types** - Use `hatch run lint:typing -- <file>` after adding type annotations

## Quick Start

**Run all checks (broad validation):**
```bash
hatch run lint:checks
```

**Format and validate a specific file:**
```bash
hatch run lint:fmt -- path/to/file.py
```

**Check types on a specific file:**
```bash
hatch run lint:typing -- path/to/file.py
```

## Available Lint Scripts

### Code Formatting

#### `fmt` - Format code (recommended for most edits)
Formats and validates code style using Ruff.

**Usage:**
```bash
# Format entire codebase
hatch run lint:fmt

# Format specific files
hatch run lint:fmt -- ddtrace/tracer.py tests/test_tracer.py

# Format specific directory
hatch run lint:fmt -- ddtrace/contrib/flask/
```

**What it does:**
1. Runs the Ruff formatter
2. Runs Ruff with --fix to auto-fix issues
3. Re-validates with style checks

**When to use:** After making code changes to automatically format and fix style issues.

#### `fmt-snapshots` - Format snapshot files
Formats snapshot test files used in snapshot-based testing.

**Usage:**
```bash
hatch run lint:fmt-snapshots -- tests/snapshots/
```

**When to use:** After snapshot test updates or when snapshot files need reformatting.

### Style Checking

#### `style` - Check all style issues (no auto-fix)
Validates code style without automatically fixing issues.

**Usage:**
```bash
# Check entire codebase
hatch run lint:style

# Check specific files
hatch run lint:style -- ddtrace/
```

**What it validates:**
- Ruff formatting
- Ruff linting rules
- Cython linting
- C code formatting
- CMake formatting

**When to use:** To verify style compliance before committing without auto-fixes.

#### `format_check` - Check formatting

Validates Python code formatting with `ruff format` (no auto-fix).

**Usage:**
```bash
hatch run lint:format_check -- ddtrace/tracer.py
```

**When to use:** Quick check of Python formatting before committing.

### Type Checking

#### `typing` - Type check with mypy
Validates Python type hints and catches type-related errors.

**Usage:**
```bash
# Check all types
hatch run lint:typing

# Check specific files (mypy path format)
hatch run lint:typing -- ddtrace/tracer.py
```

**When to use:** After adding type hints or modifying functions with type annotations.

### Security Checks

#### `security` - Security audit with Bandit
Scans code for common security issues and vulnerabilities.

**Usage:**
```bash
# Scan entire codebase
hatch run lint:security

# Scan specific directory
hatch run lint:security -- -r ddtrace/contrib/
```

**When to use:** Before committing code that handles user input, credentials, or sensitive operations.

### Spelling and Documentation

#### `spelling` - Check spelling
Validates spelling in documentation, comments, and docstrings.

**Usage:**
```bash
# Check all spelling
hatch run lint:spelling

# Check specific files
hatch run lint:spelling -- docs/ releasenotes/
```

**When to use:** Before committing documentation or user-facing text.

### Test Infrastructure

#### `riot` - Validate riotfile
Doctests the riotfile to ensure test venv definitions are valid.

**Usage:**
```bash
hatch run lint:riot
```

**When to use:** After modifying `riotfile.py` to validate syntax and doctest examples.

#### `suitespec-check` - Validate test suite specifications
Checks that test suite patterns in `tests/suitespec.yml` cover all test files.

**Usage:**
```bash
hatch run lint:suitespec-check
```

**When to use:** After adding new test files or modifying suite specifications.

#### `error-log-check` - Validate error log messages
Ensures error log messages follow project conventions.

**Usage:**
```bash
hatch run lint:error-log-check
```

**When to use:** After adding new error logging statements.

### Code Analysis

#### `sg` - Static analysis with ast-grep
Performs static code analysis using ast-grep patterns.

**Usage:**
```bash
# Scan all files
hatch run lint:sg

# Scan specific directory
hatch run lint:sg -- ddtrace/
```

**When to use:** To find code patterns that may need refactoring or optimization.

#### `sg-test` - Test ast-grep rules
Validates ast-grep rule definitions.

**Usage:**
```bash
hatch run lint:sg-test
```

**When to use:** After modifying ast-grep rules or patterns.

### C/CMake Formatting

#### `cformat_check` - Check C code formatting
Validates C code formatting.

**Usage:**
```bash
hatch run lint:cformat_check
```

**When to use:** After modifying C extension code.

#### `cmakeformat_check` - Check CMake formatting
Validates CMake file formatting.

**Usage:**
```bash
hatch run lint:cmakeformat_check
```

**When to use:** After modifying CMakeLists.txt or other CMake files.

## Common Workflows

### Workflow 1: Quick File Format and Check
After editing a Python file, format and validate it:

```bash
# Edit the file...
# Then run:
hatch run lint:fmt -- path/to/edited/file.py
```

### Workflow 2: Type Check After Adding Types
After adding type hints:

```bash
hatch run lint:typing -- ddtrace/contrib/flask/patch.py
```

### Workflow 3: Full Validation Before Commit
Run all checks before creating a commit:

```bash
hatch run lint:checks
```

This runs:
- style checks
- typing checks
- spelling checks
- riot validation
- security checks
- suitespec validation
- error log validation
- ast-grep analysis

### Workflow 4: Security Review
Before committing code handling sensitive operations:

```bash
hatch run lint:security -- -r ddtrace/contrib/
```

### Workflow 5: Documentation Review
After writing documentation or docstrings:

```bash
hatch run lint:spelling -- docs/ ddtrace/
```

## Best Practices

### DO ✅

- **Format files immediately after editing**: Use `hatch run lint:fmt -- <file>` to auto-fix style issues
- **Run `lint:checks` before pushing**: Ensures all quality gates pass
- **Target specific files**: Use `-- <file>` syntax to validate only what you changed
- **Check types early**: Run `lint:typing` after adding type annotations
- **Read error messages**: Understand what lint failures mean before fixing

### DON'T ❌

- **Ignore lint failures**: They indicate potential bugs or style issues
- **Manually fix issues that auto-fix can handle**: Use `fmt` instead
- **Commit without running lint:checks**: Let automation catch issues before push
- **Run lint:checks every time for small changes**: Use targeted commands during development

## Passing Arguments

All lint commands support passing arguments with `--` syntax:

```bash
# Basic format
hatch run lint:<script> -- <args>

# Examples:
hatch run lint:fmt -- ddtrace/tracer.py                    # Format specific file
hatch run lint:typing -- ddtrace/                           # Type check directory
hatch run lint:security -- -r ddtrace/contrib/              # Security scan with args
hatch run lint:spelling -- docs/ releasenotes/              # Spelling check specific paths
```

## Troubleshooting

### Formatting keeps failing
Ensure you've run `hatch run lint:fmt` to auto-fix style issues first:
```bash
hatch run lint:fmt -- <file>
hatch run lint:style -- <file>  # Should now pass
```

### Type errors after editing
Make sure type hints are correct and all imports are available:
```bash
hatch run lint:typing -- <file>
```

### Lint command not found
Ensure you're running from the project root:
```bash
cd /path/to/dd-trace-py
hatch run lint:checks
```

### Too many errors to fix manually
Use `fmt` to auto-fix most issues:
```bash
hatch run lint:fmt -- .
```

## Related

- **run-tests skill**: For validating that changes don't break tests
- **hatch.toml**: Source of truth for all lint configurations
- **riotfile.py**: Defines test venvs and combinations