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 hatch run lint:fmt -- <file> immediately after code changes

• Run comprehensive checks before committing - Use hatch run 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 hatch run lint:typing -- <file> after adding type annotations

Quick Start

Run all checks (broad validation):

hatch run lint:checks

Format and validate a specific file:

hatch run lint:fmt -- path/to/file.py

Check types on a specific file:

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:

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:

• 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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

hatch run lint:cformat_check

When to use: After modifying C extension code.

cmakeformat_check

• Check CMake formatting

Validates CMake file formatting.

Usage:

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:

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:

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

Workflow 3: Full Validation Before Commit

Run all checks before creating a commit:

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:

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

Workflow 5: Documentation Review

After writing documentation or docstrings:

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:

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:

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:

hatch run lint:typing -- <file>

Lint command not found

Ensure you're running from the project root:

cd /path/to/dd-trace-py hatch run lint:checks

Too many errors to fix manually

Use fmt to auto-fix most issues:

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