.

karbassi · karbassi · commit f86a05e3ac52 · 2025-07-24T21:56:33.000-05:00
diff --git a/.kiro/specs/black-to-ruff-migration/design.md b/.kiro/specs/black-to-ruff-migration/design.md
@@ -28,25 +28,32 @@ Ruff will be configured in `pyproject.toml` using the `[tool.ruff]` section with
 
 #### pyproject.toml Updates
 
+**Rationale**: Centralizing all tool configuration in pyproject.toml follows Python packaging standards and simplifies maintenance.
+
 - Remove `[tool.black]` section
 - Remove `[tool.isort]` section
 - Add comprehensive `[tool.ruff]` configuration
 - Add Ruff as a development dependency in the "# Development & Debugging" section alongside django-debug-toolbar
+- Remove Black and isort from dependencies if present
 
 #### Pre-commit Configuration Updates
 
+**Rationale**: Maintaining pre-commit integration ensures code quality checks remain automated and consistent across the development team.
+
 - Replace Black hook (currently using psf/black rev 23.3.0) with Ruff formatter hook
 - Replace isort hook (currently using pycqa/isort rev 5.12.0) with Ruff import sorting hook
 - Maintain existing exclusion patterns for migrations and .vscode folders
 - Keep all other pre-commit hooks unchanged (trailing-whitespace, end-of-file-fixer, etc.)
 
 #### Documentation Updates
 
+**Rationale**: Comprehensive documentation updates ensure all team members and new contributors understand the current tooling and maintain consistency across the project.
+
 - Update `.kiro/steering/tech.md` Code Quality Tools section to reference Ruff instead of Black and isort
 - Update `.kiro/steering/structure.md` Development Conventions section to reference Ruff formatting
 - Check and update `README.md` if it contains references to Black or isort
 - Update any developer setup instructions to include Ruff-specific commands
-- Ensure all documentation maintains consistency with Ruff usage and 79-character line length
+- Ensure all documentation maintains consistency with Ruff usage
 
 ### Ruff Configuration Sections
 
@@ -56,39 +63,15 @@ Based on the current Black and isort configuration, Ruff will be configured as f
 
 ```toml
 [tool.ruff]
-line-length = 79
 target-version = "py311"
 exclude = [migrations, build artifacts, etc.]
 ```
 
-#### Formatter Settings
-
-```toml
-[tool.ruff.format]
-quote-style = "double"
-indent-style = "space"
-skip-source-first-line = false
-line-ending = "auto"
-```
-
 #### Import Sorting Settings
 
-```toml
-[tool.ruff.isort]
-known-django = ["django"]
-section-order = ["future", "standard-library", "django", "third-party", "first-party", "local-folder"]
-combine-as-imports = true
-force-wrap-aliases = true
-split-on-trailing-comma = true
-```
+**Rationale**: Django-aware import sorting maintains the existing project's import organization patterns while leveraging Ruff's performance benefits. This ensures proper separation of Django imports from other third-party libraries, maintaining the project's existing import organization standards.
 
-#### Linting Rules
 
-```toml
-[tool.ruff.lint]
-select = ["E", "F", "W", "I"]  # Basic error, warning, and import rules
-ignore = []  # Project-specific ignores if needed
-```
 
 ## Data Models
 
@@ -119,11 +102,15 @@ No data models are affected by this migration as it only changes development too
 
 ### Validation Steps
 
+**Rationale**: These validation steps ensure the migration maintains code quality and formatting consistency while verifying all requirements are met.
+
 1. Install Ruff and configure in pyproject.toml
-2. Run `ruff format --check` on codebase to verify compatibility
-3. Run `ruff check --select I` to test import sorting
-4. Test pre-commit hooks in isolated environment
-5. Compare output with existing Black/isort formatting
+2. Run `docker compose run --rm app uv run ruff format --check .` on codebase to verify compatibility (respects pyproject.toml settings)
+3. Run `docker compose run --rm app uv run ruff check --select I .` to test import sorting (respects pyproject.toml settings)
+4. Test pre-commit hooks in containerized environment using `docker compose run --rm app pre-commit run --all-files`
+5. Compare output with existing Black/isort formatting to ensure consistency
+6. Verify uv commands work correctly with Ruff (addresses Requirement 4.4)
+7. Confirm migrations are properly excluded from formatting and linting
 
 ### Performance Verification
 
@@ -134,9 +121,11 @@ No data models are affected by this migration as it only changes development too
 
 ### Dependency Management
 
-- Ruff will be added to the "# Development & Debugging" section in pyproject.toml dependencies (following the existing organizational pattern where development tools like django-debug-toolbar are grouped)
-- Black and isort configurations will be removed from pyproject.toml (they are not explicitly listed as dependencies, only configured)
-- uv will handle Ruff installation and version management
+**Rationale**: Proper dependency management ensures Ruff is available in all development environments and follows the project's existing organizational patterns.
+
+- Ruff will be added to the "# Development & Debugging" section in pyproject.toml dependencies (addresses Requirement 4.1, 4.3)
+- Black and isort configurations will be removed from pyproject.toml (addresses Requirement 4.2)
+- uv will handle Ruff installation and version management (addresses Requirement 4.4)
 - Ruff will be placed appropriately within the development tools section to maintain logical grouping
 
 ### Backward Compatibility
@@ -150,3 +139,15 @@ No data models are affected by this migration as it only changes development too
 - Developers will need to update their local pre-commit hooks
 - IDE integrations may need to be updated to use Ruff instead of Black
 - Documentation will guide developers through the transition
+
+## Requirements Traceability
+
+This design addresses all requirements from the requirements document:
+
+**Requirement 1 (Tool Replacement)**: Addressed through pyproject.toml configuration sections that replace Black and isort with Ruff while maintaining migration exclusions, and Django-aware import sorting.
+
+**Requirement 2 (Pre-commit Integration)**: Addressed through pre-commit configuration updates that replace Black and isort hooks with Ruff equivalents while maintaining existing exclusion patterns.
+
+**Requirement 3 (Documentation Updates)**: Addressed through systematic updates to steering documents, README, and developer setup instructions to reflect Ruff usage consistently.
+
+**Requirement 4 (Dependency Management)**: Addressed through adding Ruff to development dependencies and removing Black/isort configurations, with uv handling installation and version management.
diff --git a/.kiro/specs/black-to-ruff-migration/requirements.md b/.kiro/specs/black-to-ruff-migration/requirements.md
@@ -14,15 +14,14 @@ This feature involves migrating the We All Code Django project from using Black
 
 1. WHEN the project is configured THEN Ruff SHALL replace Black as the code formatter
 2. WHEN the project is configured THEN Ruff SHALL replace isort for import sorting
-3. WHEN Ruff is configured THEN it SHALL maintain the existing 79-character line length
-4. WHEN Ruff is configured THEN it SHALL exclude migrations from formatting (same as current Black config)
-5. WHEN Ruff is configured THEN it SHALL maintain Django-aware import sorting sections
+3. WHEN Ruff is configured THEN it SHALL exclude migrations from formatting (same as current Black config)
+4. WHEN Ruff is configured THEN it SHALL maintain Django-aware import sorting sections with proper separation of Django imports from other third-party libraries
 
 ### Requirement 2: Pre-commit Integration
 
 **User Story:** As a developer, I want the pre-commit hooks updated to use Ruff, so that code quality checks run automatically before commits.
 
-#### Pre-commit Acceptance Criteria
+#### Acceptance Criteria
 
 1. WHEN pre-commit hooks are updated THEN they SHALL use Ruff instead of Black and isort
 2. WHEN pre-commit runs THEN it SHALL format code using Ruff
@@ -33,20 +32,19 @@ This feature involves migrating the We All Code Django project from using Black
 
 **User Story:** As a developer, I want all project documentation updated to reflect the Ruff migration, so that new contributors understand the current tooling and existing developers have accurate reference materials.
 
-#### Documentation Acceptance Criteria
+#### Acceptance Criteria
 
 1. WHEN documentation is updated THEN .kiro/steering/tech.md SHALL reference Ruff instead of Black and isort in the Code Quality Tools section
 2. WHEN documentation is updated THEN .kiro/steering/structure.md SHALL reference Ruff formatting conventions instead of Black
 3. WHEN documentation is updated THEN README.md SHALL be updated if it contains references to Black or isort
 4. WHEN documentation is updated THEN any developer setup instructions SHALL include Ruff-specific commands
 5. WHEN documentation is updated THEN all references to code formatting tools SHALL be consistent with Ruff usage
-6. WHEN documentation is updated THEN it SHALL maintain accuracy about the 79-character line length requirement
 
 ### Requirement 4: Dependency Management
 
 **User Story:** As a developer, I want Ruff to be added as a project dependency, so that it's available in the development environment.
 
-#### Dependency Acceptance Criteria
+#### Acceptance Criteria
 
 1. WHEN dependencies are updated THEN Ruff SHALL be added to pyproject.toml
 2. WHEN dependencies are updated THEN Black and isort SHALL be removed from dependencies (if present)
diff --git a/.kiro/specs/black-to-ruff-migration/tasks.md b/.kiro/specs/black-to-ruff-migration/tasks.md
@@ -3,17 +3,15 @@
 - [x] 1. Configure Ruff in pyproject.toml
 
   - Remove existing [tool.black] and [tool.isort] configuration sections
-  - Add comprehensive [tool.ruff] configuration with general settings (line-length = 79, target-version = "py311", exclude migrations)
-  - Add [tool.ruff.format] section with Black-compatible settings (quote-style = "double", indent-style = "space")
-  - Add [tool.ruff.isort] section with Django-aware import sorting (known-django, section-order, combine-as-imports)
-  - Add [tool.ruff.lint] section with basic linting rules (select = ["E", "F", "W", "I"])
+  - Add comprehensive [tool.ruff] configuration with general settings (target-version = "py311", exclude migrations)
   - Add Ruff as a development dependency in the "# Development & Debugging" section alongside django-debug-toolbar
+  - Add [tool.ruff.lint] section with comprehensive linting rules
   - _Requirements: 1.1, 1.2, 1.3, 1.4, 1.5, 4.1, 4.2, 4.3, 4.4_
 
 - [x] 2. Update pre-commit configuration
 
   - Replace Black hook (psf/black) with Ruff formatter hook (charliermarsh/ruff-pre-commit)
-  - Replace isort hook (pycqa/isort) with Ruff import sorting hook using --select I flag
+  - Replace isort hook (pycqa/isort) with Ruff import sorting hook using ruff-check
   - Maintain existing exclusion patterns for migrations and .vscode folders
   - Keep all other pre-commit hooks unchanged (trailing-whitespace, end-of-file-fixer, etc.)
   - _Requirements: 2.1, 2.2, 2.3, 2.4_
@@ -23,7 +21,6 @@
 
   - Replace Black and isort references with Ruff in Code Quality Tools section
   - Update tool descriptions to reflect Ruff's combined formatting and linting capabilities
-  - Maintain 79-character line length documentation
   - _Requirements: 3.1, 3.6_
 
 - [x] 3.2 Update .kiro/steering/structure.md
@@ -35,29 +32,35 @@
 
 - [x] 3.3 Check and update README.md if needed
 
-  - Search for any references to Black or isort in README.md
-  - Update developer setup instructions to include Ruff-specific commands if present
+  - Search for any references to Black or isort in README.md (none found)
+  - Update developer setup instructions to include Ruff-specific commands if present (none needed)
   - Ensure consistency with Ruff usage throughout documentation
   - _Requirements: 3.3, 3.4, 3.5_
 
-- [ ] 4. Test Ruff configuration
-- [ ] 4.1 Validate formatting compatibility
+- [ ] 4. Enhance Ruff configuration for complete migration
+- [ ] 4.1 Complete pyproject.toml Ruff configuration
+
+  - Add exclude patterns for migrations and other directories
+  - Add [tool.ruff.isort] section with Django-aware import sorting (known-django, section-order, combine-as-imports)
+  - _Requirements: 1.1, 1.2, 1.3, 1.4, 1.5_
+
+- [ ] 5. Test Ruff configuration
+- [ ] 5.1 Validate formatting compatibility
 
-  - Run `ruff format --check` on existing codebase to verify minimal changes
-  - Compare Ruff output with current Black formatting to ensure consistency
-  - Test that 79-character line length is maintained
-  - Verify migrations are excluded from formatting
+  - Run `docker compose run --rm app uv run ruff format --check .` on existing codebase to verify minimal changes
+  - Compare Ruff output with current formatting to ensure consistency
+  - Verify migrations are excluded from formatting (configured in pyproject.toml)
   - _Requirements: 1.1, 1.3, 1.4_
 
-- [ ] 4.2 Validate import sorting
+- [ ] 5.2 Validate import sorting
 
-  - Run `ruff check --select I` to test import sorting functionality
+  - Run `docker compose run --rm app uv run ruff check --select I .` to test import sorting functionality
   - Verify Django-aware section organization is maintained
-  - Test that import sorting follows isort-compatible behavior
+  - Test that import sorting follows isort-compatible behavior using `docker compose run --rm app uv run ruff check --select I --fix .`
   - _Requirements: 1.2, 1.5_
 
-- [ ] 4.3 Test pre-commit integration
-  - Run pre-commit hooks in isolated environment to verify functionality
+- [ ] 5.3 Test pre-commit integration
+  - Run `docker compose run --rm app pre-commit run --all-files` to test pre-commit hooks in containerized environment
   - Test that Ruff hooks execute correctly and maintain exclusion patterns
-  - Verify pre-commit performance improvement with Ruff
+  - Verify pre-commit performance improvement with Ruff using `docker compose run --rm app pre-commit run ruff-format ruff-check`
   - _Requirements: 2.1, 2.2, 2.3, 2.4_
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -1,33 +1,39 @@
+exclude: "^docs/|/migrations/|devcontainer.json"
+default_stages: [pre-commit]
+minimum_pre_commit_version: "3.2.0"
+
 default_language_version:
   python: python3.11
 
-# Ignore migration folders
-exclude: '.*\/migrations\/.*'
-
 repos:
   # pre-commit hooks
   - repo: https://github.com/pre-commit/pre-commit-hooks
     rev: v5.0.0
     hooks:
-      - id: no-commit-to-branch
-        args: [--branch, main]
       - id: trailing-whitespace
       - id: end-of-file-fixer
-      - id: check-yaml
       - id: check-json
       - id: check-toml
+      - id: check-xml
+      - id: check-yaml
+      - id: debug-statements
+      - id: check-builtin-literals
+      - id: check-case-conflict
+      - id: check-docstring-first
+      - id: detect-private-key
+      - id: no-commit-to-branch
+        args: [--branch, main]
       - id: check-added-large-files
       - id: check-merge-conflict
-      - id: detect-private-key
       - id: mixed-line-ending
         args: [--fix=lf]
 
-  # ruff
+  # Run the Ruff linter.
   - repo: https://github.com/astral-sh/ruff-pre-commit
     rev: v0.12.5
     hooks:
-      # Run the linter.
+      # Linter
       - id: ruff-check
-        args: [--fix]
-      # Run the formatter.
+        args: [--fix, --exit-non-zero-on-fix]
+      # Formatter
       - id: ruff-format
diff --git a/pyproject.toml b/pyproject.toml
@@ -79,10 +79,85 @@ Homepage = "https://github.com/weallcode/website"
 [tool.ruff]
 # Use Ruff's recommended defaults
 target-version = "py311"
+# Exclude a variety of commonly ignored directories.
+extend-exclude = [
+    "*/migrations/*.py",
+    "staticfiles/*",
+]
+
+select = [
+  "F",
+  "E",
+  "W",
+  "C90",
+  "I",
+  "N",
+  "UP",
+  "YTT",
+  # "ANN", # flake8-annotations: we should support this in the future but 100+ errors atm
+  "ASYNC",
+  "S",
+  "BLE",
+  "FBT",
+  "B",
+  "A",
+  "COM",
+  "C4",
+  "DTZ",
+  "T10",
+  "DJ",
+  "EM",
+  "EXE",
+  "FA",
+  'ISC',
+  "ICN",
+  "G",
+  'INP',
+  'PIE',
+  "T20",
+  'PYI',
+  'PT',
+  "Q",
+  "RSE",
+  "RET",
+  "SLF",
+  "SLOT",
+  "SIM",
+  "TID",
+  "TC",
+  "INT",
+  # "ARG", # Unused function argument
+  "PTH",
+  "ERA",
+  "PD",
+  "PGH",
+  "PL",
+  "TRY",
+  "FLY",
+  # "NPY",
+  # "AIR",
+  "PERF",
+  # "FURB",
+  # "LOG",
+  "RUF",
+]
+ignore = [
+  "S101", # Use of assert detected https://docs.astral.sh/ruff/rules/assert/
+  "RUF012", # Mutable class attributes should be annotated with `typing.ClassVar`
+  "SIM102", # sometimes it's better to nest
+  "UP038", # Checks for uses of isinstance/issubclass that take a tuple
+          # of types for comparison.
+          # Deactivated because it can make the code slow:
+          # https://github.com/astral-sh/ruff/issues/7871
+]
+# The fixes in extend-unsafe-fixes will require
+# provide the `--unsafe-fixes` flag when fixing.
+extend-unsafe-fixes = [
+  "UP038",
+]
 
-[tool.ruff.lint]
-# Allow wildcard imports in __init__.py files (common Django pattern)
-per-file-ignores = {"__init__.py" = ["F403", "F401"]}
+[tool.ruff.lint.isort]
+force-single-line = true
 
 [dependency-groups]
 dev = [
