dev-tools/README.md

Development Tools

This directory contains local development infrastructure that mirrors the GitHub Actions CI/CD pipeline to prevent failures and improve development workflow.

🛠️ Available Tools

local-ci-check.sh

Complete CI/CD pipeline simulation that runs all checks that GitHub Actions will perform:

• Black formatting check (88-character line length)
• isort import sorting check (black-compatible profile)
• flake8 linting (excludes E203/W503 for black compatibility)
• pytest test suite (runs all 45+ tests)
• Git status check (warns about uncommitted changes)

./dev-tools/local-ci-check.sh

format.sh

Quick formatting utility that automatically fixes common formatting issues:

• Runs black to format code
• Runs isort to sort imports
• Checks flake8 compliance after formatting

./dev-tools/format.sh

🚀 Makefile Commands

For convenience, all tools are also available through the root-level Makefile:

make help        # Show available commands
make format      # Quick format (uses format.sh)
make check       # Check formatting only
make test        # Run test suite only
make ci-check    # Full CI pipeline (uses local-ci-check.sh)
make install     # Install development dependencies
make clean       # Clean cache files

⚙️ Configuration Files

The development tools use these configuration files (located in project root):

• .flake8: Linting configuration with black-compatible settings
• pyproject.toml: Tool configurations for black, isort, and pytest
• Makefile: Convenient command aliases

🔄 Recommended Workflow

# 1. Make your changes
# 2. Format code
make format

# 3. Run full CI check
make ci-check

# 4. If everything passes, commit and push
git add .
git commit -m "Your commit message"
git push origin your-branch

🎯 Benefits

• Prevent CI/CD failures before pushing to GitHub
• Consistent code quality across all team members
• Fast feedback loop (~8 seconds for full check)
• Team collaboration through standardized development tools
• Automated fixes for common formatting issues

📝 Notes

• All tools respect the project's virtual environment (./venv/)
• Configuration matches GitHub Actions pre-commit hooks exactly
• Scripts provide helpful error messages and suggested fixes
• Designed to be run frequently during development