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 -- immediately after code changes Run comprehensive checks before committing - Use hatch run lint:checks before pushing Target specific files - Use -- 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 -- 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 --

to auto-fix style issues

Run

lint:checks

before pushing

Ensures all quality gates pass

Target specific files

Use

--

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