docs(arch): integrate architecture validation into QA workflow

- Add arch-check, arch-check-file, arch-check-object Makefile targets - Include arch-check in QA target for CI integration - Update architecture-rules.md with CLI usage examples - Update code-quality.md with validation commands 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
2025-12-03 21:31:41 +01:00
parent 69aff0ca30
commit 96bdb07fb2
3 changed files with 131 additions and 9 deletions
--- a/35
+++ b/35
@@ -1,7 +1,7 @@
 # Wizamart Multi-Tenant E-Commerce Platform Makefile
 # Cross-platform compatible (Windows & Linux)

-.PHONY: install install-dev install-docs install-all dev test test-coverage lint format check docker-build docker-up docker-down clean help npm-install tailwind-dev tailwind-build
+.PHONY: install install-dev install-docs install-all dev test test-coverage lint format check docker-build docker-up docker-down clean help npm-install tailwind-dev tailwind-build arch-check arch-check-file arch-check-object

 # Detect OS
 ifeq ($(OS),Windows_NT)
@@ -224,7 +224,33 @@ verify-imports:
 	@echo "Verifying critical imports..."
 	$(PYTHON) scripts/verify_critical_imports.py

-qa: format lint test-coverage docs-check
+arch-check:
+	@echo "Running architecture validation..."
+	$(PYTHON) scripts/validate_architecture.py
+
+arch-check-file:
+ifeq ($(DETECTED_OS),Windows)
+	@if "$(file)"=="" (echo Error: Please provide a file. Usage: make arch-check-file file="path/to/file.py") else ($(PYTHON) scripts/validate_architecture.py -f "$(file)")
+else
+	@if [ -z "$(file)" ]; then \
+		echo "Error: Please provide a file. Usage: make arch-check-file file=\"path/to/file.py\""; \
+	else \
+		$(PYTHON) scripts/validate_architecture.py -f "$(file)"; \
+	fi
+endif
+
+arch-check-object:
+ifeq ($(DETECTED_OS),Windows)
+	@if "$(name)"=="" (echo Error: Please provide an object name. Usage: make arch-check-object name="company") else ($(PYTHON) scripts/validate_architecture.py -o "$(name)")
+else
+	@if [ -z "$(name)" ]; then \
+		echo "Error: Please provide an object name. Usage: make arch-check-object name=\"company\""; \
+	else \
+		$(PYTHON) scripts/validate_architecture.py -o "$(name)"; \
+	fi
+endif
+
+qa: format lint arch-check test-coverage docs-check
 	@echo "Quality assurance checks completed!"

 # =============================================================================
@@ -388,9 +414,12 @@ help:
 	@echo "  lint                 - Lint and auto-fix with ruff + mypy"
 	@echo "  lint-strict          - Lint without auto-fix + mypy"
 	@echo "  verify-imports       - Verify critical imports haven't been removed"
+	@echo "  arch-check           - Validate architecture patterns"
+	@echo "  arch-check-file file=\"path\" - Check a single file"
+	@echo "  arch-check-object name=\"company\" - Check all files for an entity"
 	@echo "  check                - Format + lint + verify imports"
 	@echo "  ci                   - Full CI pipeline (strict)"
-	@echo "  qa                   - Quality assurance"
+	@echo "  qa                   - Quality assurance (includes arch-check)"
 	@echo ""
 	@echo "=== DOCUMENTATION ==="
 	@echo "  docs-serve           - Start documentation server"
--- a/docs/development/architecture-rules.md
+++ b/docs/development/architecture-rules.md
@@ -12,18 +12,60 @@ The architecture validator ensures consistent patterns, separation of concerns,

 ## Running the Validator

+### Using Make Commands (Recommended)
+
+```bash
+# Check all files
+make arch-check
+
+# Check a single file
+make arch-check-file file="app/api/v1/admin/vendors.py"
+
+# Check all files related to an entity (company, vendor, user, etc.)
+make arch-check-object name="company"
+make arch-check-object name="vendor"
+
+# Full QA (includes arch-check)
+make qa
+```
+
+### Using Python Directly
+
 ```bash
 # Check all files
 python scripts/validate_architecture.py

 # Check specific directory
-python scripts/validate_architecture.py app/api/
+python scripts/validate_architecture.py -d app/api/
+
+# Check a single file
+python scripts/validate_architecture.py -f app/api/v1/admin/vendors.py
+
+# Check all files for an entity
+python scripts/validate_architecture.py -o company
+python scripts/validate_architecture.py -o vendor

 # Verbose output
 python scripts/validate_architecture.py --verbose

-# Auto-fix where possible
-python scripts/validate_architecture.py --fix
+# JSON output (for CI/CD)
+python scripts/validate_architecture.py --json
+```
+
+### Output Format
+
+The validator displays a summary table for validated files:
+
+```
+📋 FILE SUMMARY:
+--------------------------------------------------------------------------------
+  File                           Status    Errors   Warnings
+  -----------------------------  --------  -------  --------
+  app/api/v1/admin/companies.py  ❌ FAILED  6        9
+  app/services/company_service.py ✅ PASSED  0        0
+  models/database/company.py     ✅ PASSED  0        0
+--------------------------------------------------------------------------------
+  Total: 3 files | ✅ 2 passed | ❌ 1 failed | 6 errors | 9 warnings
 ```

 ## Severity Levels
--- a/docs/development/code-quality.md
+++ b/docs/development/code-quality.md
@@ -171,9 +171,12 @@ show_missing = true
 | `make format` | Format code with Ruff | Before committing |
 | `make lint` | Lint and auto-fix with Ruff + mypy | Before committing |
 | `make lint-strict` | Lint without auto-fix + mypy | In CI/CD pipelines |
+| `make arch-check` | Validate architecture patterns | Before committing |
+| `make arch-check-file file="path"` | Check a single file | Quick validation |
+| `make arch-check-object name="company"` | Check all files for an entity | Entity-wide validation |
 | `make check` | Run format + lint | Quick pre-commit check |
 | `make ci` | Full CI pipeline (strict lint + coverage) | CI/CD workflows |
-| `make qa` | Quality assurance (format + lint + coverage + docs) | Before releases |
+| `make qa` | Quality assurance (format + lint + arch-check + coverage + docs) | Before releases |

 ### Testing Commands

@@ -185,6 +188,51 @@ show_missing = true
 | `make test-coverage` | Run tests with coverage report |
 | `make test-fast` | Run fast tests (skip slow ones) |

+## Architecture Validation
+
+The architecture validator ensures code follows established patterns and best practices.
+
+### Quick Start
+
+```bash
+# Check all files
+make arch-check
+
+# Check a single file
+make arch-check-file file="app/api/v1/admin/vendors.py"
+
+# Check all files related to an entity
+make arch-check-object name="company"
+make arch-check-object name="vendor"
+```
+
+### What It Checks
+
+| Category | Examples |
+|----------|----------|
+| **API Endpoints** | Pydantic models, no business logic, exception handling, auth |
+| **Service Layer** | No HTTPException, proper exceptions, DB session as param |
+| **Models** | SQLAlchemy/Pydantic separation |
+| **JavaScript** | Centralized logger, apiClient usage |
+| **Templates** | Base template inheritance |
+
+### Output
+
+The validator provides a summary table showing pass/fail status per file:
+
+```
+📋 FILE SUMMARY:
+--------------------------------------------------------------------------------
+  File                           Status    Errors   Warnings
+  -----------------------------  --------  -------  --------
+  app/api/v1/admin/companies.py  ❌ FAILED  6        9
+  app/services/company_service.py ✅ PASSED  0        0
+--------------------------------------------------------------------------------
+  Total: 2 files | ✅ 1 passed | ❌ 1 failed | 6 errors | 9 warnings
+```
+
+See [Architecture Rules Reference](architecture-rules.md) for detailed rule documentation.
+
 ## Pre-Commit Workflow

 Before committing code:
@@ -193,10 +241,13 @@ Before committing code:
 # 1. Format, lint, and verify critical imports
 make check

-# 2. Run relevant tests
+# 2. Validate architecture patterns
+make arch-check
+
+# 3. Run relevant tests
 make test-fast

-# 3. If all passes, commit
+# 4. If all passes, commit
 git add .
 git commit -m "your message"
 ```