From 96bdb07fb2c890051fb6962742faf7991832b3af Mon Sep 17 00:00:00 2001 From: Samir Boulahtit Date: Wed, 3 Dec 2025 21:31:41 +0100 Subject: [PATCH] docs(arch): integrate architecture validation into QA workflow MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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 --- Makefile | 35 ++++++++++++++-- docs/development/architecture-rules.md | 48 ++++++++++++++++++++-- docs/development/code-quality.md | 57 ++++++++++++++++++++++++-- 3 files changed, 131 insertions(+), 9 deletions(-) diff --git a/Makefile b/Makefile index 7eb0686a..f85c6422 100644 --- a/Makefile +++ b/Makefile @@ -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" diff --git a/docs/development/architecture-rules.md b/docs/development/architecture-rules.md index f2cb0242..0fc0be42 100644 --- 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 diff --git a/docs/development/code-quality.md b/docs/development/code-quality.md index 776d1152..e6de6d13 100644 --- 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" ```