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