tox.ini

# =============================================================================
# Tox Configuration
# https://tox.wiki/en/stable/
# =============================================================================
#
# This file is portable - copy to other repos without modification.
#
# Tox automates testing across multiple Python versions and Django versions,
# runs linters, type checkers, formatters, and security scanners in isolated
# virtual environments.
#
# Usage:
#   tox                    Run all default environments (envlist)
#   tox -e py312           Run single environment
#   tox -e lint,typecheck  Run multiple specific environments
#   tox -p auto            Run environments in parallel
#   tox -l                 List all available environments
#   tox --recreate         Force recreate virtual environments
#
# =============================================================================


# =============================================================================
# Global Settings
# =============================================================================

[tox]

# Default environments to run (order matters for CI output)
envlist =
    # Python 3.12 with Django versions
    py312-django50
    py312-django51
    py312-django52
    py312-django60
    # Python 3.13 with Django versions
    py313-django50
    py313-django51
    py313-django52
    py313-django60
    # Python 3.14 with Django versions
    py314-django50
    py314-django51
    py314-django52
    py314-django60
    # Python 3.15 with Django versions
    py315-django50
    py315-django51
    py315-django52
    py315-django60
    # Code quality checks
    lint
    typecheck
    security

# Use PEP 517/518 build system (pyproject.toml)
isolated_build = true

# Don't fail if Python version not installed (useful for local dev)
skip_missing_interpreters = true


# =============================================================================
# Test Environment (Default)
# =============================================================================
#
# Runs pytest with coverage against the swing.wellknown package.
# Matrix: Python versions × Django versions
#
# Examples:
#   tox -e py312-django51     # Python 3.12 + Django 5.1
#   tox -e py313-django60     # Python 3.13 + Django 6.0
#   tox -- -k "test_model"    # Pass args to pytest
#
# =============================================================================

[testenv]
description = Run tests with pytest

# Install Django version based on factor (e.g., django51 → Django>=5.1,<5.2)
deps =
    django50: Django>=5.0,<5.1
    django51: Django>=5.1,<5.2
    django52: Django>=5.2,<5.3
    django60: Django>=6.0,<6.1
    pytest>=8.0
    pytest-django>=4.5
    pytest-cov>=4.0
    coverage[toml]>=7.0

# Environment variables for Django
setenv =
    DJANGO_SETTINGS_MODULE = tst.settings
    PYTHONPATH = {toxinidir}/src:{toxinidir}

# Run pytest with coverage; {posargs} allows extra args via: tox -- -k "test_"
commands =
    pytest tst/ --cov=swing.wellknown --cov-branch --cov-fail-under=60 {posargs}

# Pass through environment variables (needed for CI and some tools)
passenv =
    HOME
    USER
    CI
    GITHUB_*


# =============================================================================
# Python Linting
# =============================================================================
#
# Static analysis for Python code quality and style.
#
# Run: tox -e lint
#
# =============================================================================

[testenv:lint]
description = Run linters (flake8, pylint)

# Don't install the package itself
skip_install = true

deps =
    flake8>=7.0
    pylint>=3.0
    pylint-django>=2.5

commands =
    # flake8: PEP 8 style + common errors
    flake8 src/
    # pylint: deeper analysis (errors only for speed)
    pylint src/ --errors-only


# =============================================================================
# Type Checking
# =============================================================================
#
# Static type analysis with mypy for catching type errors.
#
# Run: tox -e typecheck
#
# =============================================================================

[testenv:typecheck]
description = Run type checker (mypy)

deps =
    mypy>=1.8
    django-stubs>=4.2
    types-requests

commands =
    mypy src/


# =============================================================================
# Format Checking
# =============================================================================
#
# Verify code formatting without making changes.
# Use format-fix to auto-fix issues.
#
# Run: tox -e format
#
# =============================================================================

[testenv:format]
description = Check code formatting
skip_install = true

deps =
    black>=24.0
    isort>=5.13
    add-trailing-comma>=4.0
    docformatter>=1.7

commands =
    # Check black formatting
    black --check --config .black.toml src/ tst/
    # Check import sorting
    isort --check-only src/ tst/
    # Check docstring formatting
    docformatter --check --diff --recursive src/ tst/


# =============================================================================
# Auto-Format Code
# =============================================================================
#
# Automatically fix formatting issues in-place.
# Order matters: trailing commas → docstrings → imports → black
#
# Run: tox -e format-fix
#
# =============================================================================

[testenv:format-fix]
description = Auto-format code with black, isort, docformatter, and add-trailing-comma
skip_install = true

# Allow bash for find command
allowlist_externals = bash

deps =
    black>=24.0
    isort>=5.13
    add-trailing-comma>=4.0
    docformatter>=1.7

commands =
    # 1. Add trailing commas (prevents diff noise)
    bash -c "find src tst -name '*.py' -exec add-trailing-comma --exit-zero-even-if-changed {} +"
    # 2. Format docstrings (Google style, 79 chars)
    docformatter --in-place --recursive --pre-summary-newline --close-quotes-on-newline --make-summary-multi-line --wrap-summaries 79 --wrap-descriptions 79 src/ tst/
    # 3. Sort imports
    isort src/ tst/
    # 4. Format code (must be last - definitive style)
    black --config .black.toml src/ tst/


# =============================================================================
# Security Scanning
# =============================================================================
#
# Scan for common security issues with bandit.
#
# Run: tox -e security
#
# =============================================================================

[testenv:security]
description = Run security checks with bandit
skip_install = true

deps =
    bandit[toml]>=1.7

commands =
    bandit -r src/ -c .bandit.yaml


# =============================================================================
# JavaScript/TypeScript Linting
# =============================================================================
#
# Lint frontend code with ESLint (requires Node.js).
#
# Run: tox -e lint-js
#
# =============================================================================

[testenv:lint-js]
description = Lint JavaScript/TypeScript with ESLint
skip_install = true

# Allow npx command (Node.js)
allowlist_externals = npx

commands =
    npx eslint src/ --ext .js,.ts,.jsx,.tsx


# =============================================================================
# CSS/SCSS Linting
# =============================================================================
#
# Lint stylesheets with Stylelint (requires Node.js).
#
# Run: tox -e lint-css
#
# =============================================================================

[testenv:lint-css]
description = Lint CSS/SCSS with Stylelint
skip_install = true

allowlist_externals = npx

commands =
    npx stylelint "src/**/*.{css,scss}"


# =============================================================================
# HTML/Template Linting
# =============================================================================
#
# Lint Django/Jinja templates with djLint.
#
# Run: tox -e lint-html
#
# =============================================================================

[testenv:lint-html]
description = Lint HTML/Jinja templates with djLint
skip_install = true

deps =
    djlint>=1.36

commands =
    djlint src/ --lint


# =============================================================================
# JavaScript/CSS Formatting
# =============================================================================
#
# Format frontend code with Prettier (requires Node.js).
#
# Run: tox -e format-js
#
# =============================================================================

[testenv:format-js]
description = Format JavaScript/TypeScript/CSS/SCSS with Prettier
skip_install = true

allowlist_externals = npx

commands =
    npx prettier --write "src/**/*.{js,ts,jsx,tsx,css,scss,json}"


# =============================================================================
# HTML/Template Formatting
# =============================================================================
#
# Format Django/Jinja templates with djLint.
#
# Run: tox -e format-html
#
# =============================================================================

[testenv:format-html]
description = Format HTML/Jinja templates with djLint
skip_install = true

deps =
    djlint>=1.36

commands =
    djlint src/ --reformat


# =============================================================================
# Documentation Build
# =============================================================================
#
# Build MkDocs documentation with strict mode (fail on warnings).
#
# Run: tox -e docs
#
# =============================================================================

[testenv:docs]
description = Build documentation with mkdocs

deps =
    mkdocs>=1.5
    mkdocs-material>=9.0

commands =
    mkdocs build --strict


# =============================================================================
# Cleanup
# =============================================================================
#
# Remove temporary files, caches, and build artifacts.
#
# Run: tox -e clean
#
# =============================================================================

[testenv:clean]
description = Clean up temporary files and caches
skip_install = true

commands =
    # Remove all __pycache__ directories
    python -c "import shutil; import pathlib; [shutil.rmtree(p, ignore_errors=True) for p in pathlib.Path('.').rglob('__pycache__')]"
    # Remove tool caches and build outputs
    python -c "import shutil; [shutil.rmtree(p, ignore_errors=True) for p in ['.pytest_cache', '.mypy_cache', '.ruff_cache', 'htmlcov', 'site', '.coverage']]"


# =============================================================================
# Coverage Report
# =============================================================================
#
# Generate detailed coverage report (HTML + terminal).
# Useful for local development to inspect uncovered lines.
#
# Run: tox -e coverage
#
# =============================================================================

[testenv:coverage]
description = Generate detailed coverage report (HTML + terminal)

deps =
    Django>=5.1,<5.2
    pytest>=8.0
    pytest-django>=4.5
    pytest-cov>=4.0
    coverage[toml]>=7.0

setenv =
    DJANGO_SETTINGS_MODULE = tst.settings
    PYTHONPATH = {toxinidir}/src:{toxinidir}

commands =
    pytest tst/ --cov=swing.wellknown --cov-report=html --cov-report=term-missing