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

• Always format after editing - Use scripts/lint fmt -- <file> immediately after code changes
• Run comprehensive checks before committing - Use scripts/lint checks before pushing
• Target specific files - Use -- <file> syntax to validate only what you changed, not the entire codebase
• Fix auto-fixable issues - Use fmt instead of manually fixing style issues
• Type check after adding types - Use scripts/lint typing -- <file> after adding type annotations

Quick Start

Run all checks (broad validation):

scripts/lint checks

Format and validate a specific file:

scripts/lint fmt -- path/to/file.py

Check types on a specific file:

scripts/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:

# Format entire codebase
scripts/lint fmt

# Format specific files
scripts/lint fmt -- ddtrace/tracer.py tests/test_tracer.py

# Format specific directory
scripts/lint fmt -- ddtrace/contrib/flask/

What it does:

• Runs the Ruff formatter
• Runs Ruff with --fix to auto-fix issues
• 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:

scripts/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:

# Check entire codebase
scripts/lint style

# Check specific files
scripts/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:

scripts/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:

# Check all types
scripts/lint typing

# Check specific files (mypy path format)
scripts/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:

# Scan entire codebase
scripts/lint security

# Scan specific directory
scripts/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:

# Check all spelling
scripts/lint spelling

# Check specific files
scripts/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:

scripts/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:

scripts/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:

scripts/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:

# Scan all files
scripts/lint sg

# Scan specific directory
scripts/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:

scripts/lint sg-test

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

C/CMake Formatting

cformat - Check C code formatting

Validates C code formatting.

Usage:

scripts/lint cformat

When to use: After modifying C extension code.

cmakeformat - Check CMake formatting

Validates CMake file formatting.

Usage:

scripts/lint cmakeformat

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:

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

Workflow 2: Type Check After Adding Types

After adding type hints:

scripts/lint typing -- ddtrace/contrib/flask/patch.py

Workflow 3: Full Validation Before Commit

Run all checks before creating a commit:

scripts/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:

scripts/lint security -- -r ddtrace/contrib/

Workflow 5: Documentation Review

After writing documentation or docstrings:

scripts/lint spelling -- docs/ ddtrace/

Best Practices

DO ✅

• Format files immediately after editing: Use scripts/lint fmt -- <file> to auto-fix style issues
• Run checks before pushing: Ensures all quality gates pass
• Target specific files: Use -- <file> syntax to validate only what you changed
• Check types early: Run 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 checks: Let automation catch issues before push
• Run checks every time for small changes: Use targeted commands during development

Passing Arguments

All lint commands support passing arguments with -- syntax:

# Basic format
scripts/lint <subcommand> -- <args>

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

Troubleshooting

Formatting keeps failing

Ensure you've run scripts/lint fmt to auto-fix style issues first:

scripts/lint fmt -- <file>
scripts/lint style -- <file>  # Should now pass

Type errors after editing

Make sure type hints are correct and all imports are available:

scripts/lint typing -- <file>

Lint command not found

Ensure you're running from the project root:

cd /path/to/dd-trace-py
scripts/lint checks

Too many errors to fix manually

Use fmt to auto-fix most issues:

scripts/lint fmt -- .

Related

• run-tests skill: For validating that changes don't break tests
• pyproject.toml [dependency-groups]: Source of truth for all lint tool versions
• riotfile.py: Defines test venvs and combinations