Merge pull request #293 from christianlouis/copilot/add-ruff-setup-and-scripts

feat: add agent pre-PR ruff enforcement script and policy

AGENT_RUN_RUFF.md

@@ -0,0 +1,122 @@
+# Agent Pre-PR Ruff Policy
+
+This document defines the policy for Copilot/AI Agents when creating or updating pull requests in the DocuElevate repository.
+
+## Required Steps Before Creating/Updating a PR
+
+### 1. Run the Ruff Auto-Fix Script
+
+Before creating or updating a branch or opening a PR, **ALWAYS** run:
+
+```bash
+./scripts/run-ruff-and-fix.sh
+```
+
+### 2. Handle Script Exit Codes
+
+**If the script exits with code 0 (success):**
+- ✅ All ruff checks passed or were auto-fixed
+- Continue with PR creation process
+- Push the branch (including any auto-fix commits)
+
+**If the script exits with code non-zero (failure):**
+- ❌ Stop PR creation immediately
+- Do NOT open the PR
+- Report the ruff failures to the human user
+- Include the full `ruff check` output in your response
+- Create an issue or report the failures for manual resolution
+
+### 3. Handle Auto-Fix Commits
+
+If the script commits fixes:
+- The script will automatically commit changes with message: `style: ruff auto-fixes`
+- Push the branch with the commit(s) before continuing PR creation
+- This ensures CI sees the fixed code when the PR is opened
+
+## Example Agent Workflow
+
+```
+1. Clone repository and create feature branch
+2. Make code changes to implement feature
+3. Run: ./scripts/run-ruff-and-fix.sh
+4. Check exit code:
+   - If 0: Push branch and create PR
+   - If non-zero: Report failures, do NOT create PR
+5. Run project tests (if ruff passed)
+6. If all checks pass: Create the PR
+7. If any check fails: Report failures instead of creating PR
+```
+
+## Why This Policy Exists
+
+1. **Prevent CI Failures**: Ensures PRs don't break ruff checks in CI
+2. **Auto-Fix Minor Issues**: Automatically fixes formatting and simple linting issues
+3. **Surface Manual Issues Early**: Identifies issues that need human attention before PR creation
+4. **Maintain Code Quality**: Enforces consistent code style across the repository
+
+## Integration with Existing CI
+
+DocuElevate has two workflows that handle ruff:
+
+1. **`.github/workflows/ci.yml`** (Lint Job)
+   - Runs `ruff check` (without --fix) on all pushes and PRs
+   - Fails CI if issues are found
+   - Runs early in the pipeline to catch style issues before tests
+
+2. **`.github/workflows/ruff-auto-fix.yml`**
+   - Runs on PRs when Python files change
+   - Automatically applies `ruff --fix` and `ruff format`
+   - Commits fixes back to the PR branch
+   - Posts a comment notifying the author
+
+This agent script ensures that most issues are caught and fixed **before** the PR is created, reducing the need for the auto-fix workflow to intervene.
+
+## Local Development
+
+Developers should also use this script or set up pre-commit hooks:
+
+```bash
+# Install pre-commit hooks (recommended)
+pip install pre-commit
+pre-commit install
+
+# Or run manually before committing
+./scripts/run-ruff-and-fix.sh
+```
+
+## Troubleshooting
+
+### Script fails with "ruff: command not found"
+
+The script installs ruff automatically. If this fails:
+```bash
+pip install ruff
+```
+
+### Script fails with Git errors
+
+Ensure you're in a Git repository with proper configuration:
+```bash
+git config user.name "Your Name"
+git config user.email "your.email@example.com"
+```
+
+### Ruff issues remain after --fix
+
+Some issues cannot be auto-fixed (e.g., unused imports, complex logic issues). These require manual resolution:
+1. Review the ruff output
+2. Fix the issues manually
+3. Run the script again to verify
+
+## Configuration
+
+Ruff configuration is in `pyproject.toml` under `[tool.ruff]` and `[tool.ruff.lint]`.
+
+Default settings:
+- Line length: 120 characters
+- Target Python version: 3.11+
+- Enabled rules: Pyflakes (F), pycodestyle (E, W), isort (I), bandit (S), flake8-bugbear (B), pylint (PL)
+
+## Questions?
+
+See the [Contributing Guide](CONTRIBUTING.md) for more information on code quality standards and development workflow.

scripts/run-ruff-and-fix.sh

@@ -0,0 +1,40 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Script for local/agent use before creating a PR.
+# Installs ruff, checks, tries --fix, commits fixes, and fails if issues remain.
+
+echo "Installing ruff..."
+python -m pip install --upgrade pip --quiet
+pip install ruff --quiet
+
+echo "Running ruff check..."
+if ruff check app/ tests/; then
+  echo "✅ ruff: no issues found"
+  exit 0
+else
+  echo "⚠️  ruff: issues found — running ruff --fix"
+  ruff check app/ tests/ --fix
+  
+  # Check if there are any changes to commit
+  git add -A
+  if git diff --staged --quiet; then
+    echo "ℹ️  No staged changes after ruff --fix"
+  else
+    git commit -m "style: ruff auto-fixes" || true
+    echo "✅ Committed ruff fixes"
+  fi
+  
+  echo "Re-running ruff check after fixes..."
+  if ruff check app/ tests/; then
+    echo "✅ ruff: all issues fixed"
+    exit 0
+  else
+    echo "❌ ruff: issues remain after auto-fix" >&2
+    echo ""
+    echo "The following issues could not be auto-fixed and require manual intervention:"
+    echo ""
+    ruff check app/ tests/
+    exit 1
+  fi
+fi

tests/test_api_settings.py

@@ -1,6 +1,6 @@
 """Tests for app/api/settings.py module."""
 
-from unittest.mock import MagicMock, Mock, patch
+from unittest.mock import MagicMock, patch
 
 import pytest
 from fastapi import HTTPException