feat(validation): add OpenAPI validation script and project validation script

- Introduced `validate_openapi.sh` to check OpenAPI/Swagger resources, ensuring proper functionality and documentation.
- Added `validate_project.php` to perform comprehensive validation of the project structure, dependencies, and documentation.
- Enhanced error handling in middleware classes by throwing `HttpException` for better response management.
- Updated tests for authentication middleware to expect `HttpException` on failure.

Author: CAFernandes

.github/workflows/ci.yml

@@ -1,7 +1,7 @@
 name: CI/CD Pipeline
 
 # Optimized CI/CD using consolidated scripts with automatic version detection
-# Multi-PHP testing available locally via: ./scripts/test-all-php-versions.sh
+# Multi-PHP testing available locally via: ./scripts/testing/test-all-php-versions.sh
 
 on:
   push:
@@ -47,8 +47,8 @@ jobs:
       run: |
         echo "🔍 Running consolidated quality validation..."
         echo "📋 Using automatic version detection from VERSION file"
-        echo "💡 Multi-PHP testing done locally via: ./scripts/test-all-php-versions.sh"
-        scripts/quality-check.sh || { echo 'Quality check failed'; exit 1; }
+        echo "💡 Multi-PHP testing done locally via: ./scripts/testing/test-all-php-versions.sh"
+        scripts/quality/quality-check.sh || { echo 'Quality check failed'; exit 1; }
 
     - name: Upload coverage to Codecov
       uses: codecov/codecov-action@v4
@@ -70,8 +70,8 @@ jobs:
         echo "🔍 Used consolidated scripts with auto-version detection"
         echo ""
         echo "📋 For comprehensive testing:"
-        echo "   • Multi-PHP: ./scripts/test-all-php-versions.sh (PHP 8.1-8.4)"
-        echo "   • Full validation: ./scripts/validate_all.sh"
-        echo "   • Version management: ./scripts/version-bump.sh"
+        echo "   • Multi-PHP: ./scripts/testing/test-all-php-versions.sh (PHP 8.1-8.4)"
+        echo "   • Full validation: ./scripts/validation/validate_all.sh"
+        echo "   • Version management: ./scripts/release/version-bump.sh"
         echo ""
         echo "🚀 CI/CD optimized for speed - extensive testing done locally"

.github/workflows/pre-release.yml

@@ -6,6 +6,11 @@ on:
   push:
     branches: [ main ]
 
+permissions:
+  contents: read
+  issues: write
+  pull-requests: write
+
 jobs:
   pre-release-validation:
     runs-on: ubuntu-latest
@@ -42,13 +47,13 @@ jobs:
     - name: Run release preparation script
       run: |
         echo "🚀 Running automated release preparation..."
-        chmod +x scripts/prepare_release.sh
-        echo "n\nn\nn" | scripts/prepare_release.sh
+        chmod +x scripts/release/prepare_release.sh
+        echo "n\nn\nn" | scripts/release/prepare_release.sh
 
     - name: Run project validation
       run: |
         echo "📋 Running comprehensive project validation..."
-        php scripts/validate_project.php
+        php scripts/validation/validate_project.php
 
     - name: Check for security vulnerabilities
       run: composer audit --no-dev

.github/workflows/release.yml

@@ -44,13 +44,13 @@ jobs:
       run: |
         echo "🚀 Running comprehensive validation for release..."
         echo "📋 Using consolidated quality check with auto-version detection"
-        scripts/quality-check.sh
+        scripts/quality/quality-check.sh
         
     - name: Prepare release validation
       run: |
         echo "📦 Running release preparation validation..."
-        chmod +x scripts/prepare_release.sh
-        scripts/prepare_release.sh
+        chmod +x scripts/release/prepare_release.sh
+        scripts/release/prepare_release.sh
 
   release:
     needs: validate

CHANGELOG.md

@@ -5,27 +5,41 @@ All notable changes to the PivotPHP Framework will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [1.1.4] - 2025-07-14
+## [1.1.4] - 2025-07-15
 
 ### 🔧 **Infrastructure Consolidation & Automation Edition**
 
-> **Script Infrastructure Overhaul**: Complete consolidation of script ecosystem with 40% reduction (25 → 15 scripts), automatic version detection via mandatory VERSION file, GitHub Actions optimization, and comprehensive versioning documentation while maintaining 100% backward compatibility and zero impact on framework performance.
+> **Script Infrastructure Overhaul**: Complete consolidation and reorganization of script ecosystem with logical organization in subfolders, 40% reduction (25 → 15 scripts), automatic version detection via mandatory VERSION file, GitHub Actions optimization, and comprehensive versioning documentation while maintaining 100% backward compatibility and zero impact on framework performance.
+
+#### 📁 **Script Organization & Structure** 
+- **Logical Subfolder Organization**: Scripts organized by functionality for better maintainability
+  ```
+  scripts/
+  ├── validation/     # Validation scripts (validate_all.sh, validate-docs.sh, etc.)
+  ├── quality/        # Quality checks (quality-check.sh, validate-psr12.php)  
+  ├── release/        # Release management (prepare_release.sh, version-bump.sh)
+  ├── testing/        # Testing scripts (test-all-php-versions.sh, run_stress_tests.sh)
+  └── utils/          # Utilities (version-utils.sh, switch-psr7-version.php)
+  ```
+- **Comprehensive Documentation**: README files in each subfolder with usage examples
+- **Backward Compatibility**: All existing script names preserved, only location changed
+- **Updated Integrations**: GitHub Actions workflows, composer.json, and documentation updated
 
 #### 🔧 **Script Infrastructure Consolidation**
 - **40% Script Reduction**: Consolidated from 25 to 15 scripts, eliminating duplication
   - **Removed Scripts**: 10 duplicate/obsolete scripts eliminated
-    - `quality-check-v114.sh` → Hardcoded version, consolidated into `quality-check.sh`
-    - `validate_all_v114.sh` → Hardcoded version, consolidated into `validate_all.sh`
+    - `quality-check-v114.sh` → Hardcoded version, consolidated into `scripts/quality/quality-check.sh`
+    - `validate_all_v114.sh` → Hardcoded version, consolidated into `scripts/validation/validate_all.sh`
     - `quick-quality-check.sh` → Duplicate functionality integrated
-    - `simple_pre_release.sh` → Replaced by enhanced `prepare_release.sh`
-    - `quality-gate.sh` → Functionality consolidated into `quality-check.sh`
-    - `quality-metrics.sh` → Functionality consolidated into `quality-check.sh`
-    - `test-php-versions-quick.sh` → Replaced by `test-all-php-versions.sh`
-    - `ci-validation.sh` → Functionality consolidated into `quality-check.sh`
+    - `simple_pre_release.sh` → Replaced by enhanced `scripts/release/prepare_release.sh`
+    - `quality-gate.sh` → Functionality consolidated into `scripts/quality/quality-check.sh`
+    - `quality-metrics.sh` → Functionality consolidated into `scripts/quality/quality-check.sh`
+    - `test-php-versions-quick.sh` → Replaced by `scripts/testing/test-all-php-versions.sh`
+    - `ci-validation.sh` → Functionality consolidated into `scripts/quality/quality-check.sh`
     - `setup-precommit.sh` → One-time setup script, no longer needed
     - `adapt-psr7-v1.php` → Specific utility script removed for simplicity
 
-- **Shared Utility Library**: Created `scripts/lib/version-utils.sh` with common functions
+- **Shared Utility Library**: Created `scripts/utils/version-utils.sh` with common functions
   - `get_version()` - Automatic version detection from VERSION file
   - `get_project_root()` - Project root directory detection
   - `validate_project_context()` - PivotPHP Core context validation
@@ -38,15 +52,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - **Strict Validation**: Scripts fail immediately if VERSION file missing or invalid
   - **Portuguese Error Messages**: Clear error messages for better developer experience
 
-- **Enhanced Version Management**: New `scripts/version-bump.sh` with automation
+- **Enhanced Version Management**: New `scripts/release/version-bump.sh` with automation
   ```bash
   # Semantic version management
-  scripts/version-bump.sh patch    # 1.1.4 → 1.1.5
-  scripts/version-bump.sh minor    # 1.1.4 → 1.2.0
-  scripts/version-bump.sh major    # 1.1.4 → 2.0.0
+  scripts/release/version-bump.sh patch    # 1.1.4 → 1.1.5
+  scripts/release/version-bump.sh minor    # 1.1.4 → 1.2.0
+  scripts/release/version-bump.sh major    # 1.1.4 → 2.0.0
 
   # Preview mode
-  scripts/version-bump.sh minor --dry-run
+  scripts/release/version-bump.sh minor --dry-run
   ```
   - **Git Integration**: Automatic commit and tag creation
   - **Composer Integration**: Updates composer.json if present
@@ -108,13 +122,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **Simplified Commands**: Single entry points for complex operations
   ```bash
   # Quality validation (replaces multiple scripts)
-  scripts/quality-check.sh
+  scripts/quality/quality-check.sh
 
   # Complete validation
-  scripts/validate_all.sh
+  scripts/validation/validate_all.sh
 
   # Release preparation
-  scripts/prepare_release.sh
+  scripts/release/prepare_release.sh
   ```
 
 - **Improved Developer Experience**:
@@ -800,7 +814,7 @@ OptimizedHttpFactory::initialize([
 - **Backward Compatibility**: All v1.0.0 routes continue to work
 - **PSR-7 Dual Version Support**: Full compatibility with both PSR-7 v1.x and v2.x
   - Automatic version detection via `Psr7VersionDetector`
-  - Script to switch between versions: `scripts/switch-psr7-version.php`
+  - Script to switch between versions: `scripts/utils/switch-psr7-version.php`
   - Enables ReactPHP integration with PSR-7 v1.x
   - Maintains type safety with PSR-7 v2.x
 

CLAUDE.md

@@ -11,7 +11,7 @@ PivotPHP Core is a high-performance PHP microframework inspired by Express.js, d
 ### Development Workflow
 ```bash
 # Run comprehensive validation (includes all checks)
-./scripts/validate_all.sh
+./scripts/validation/validate_all.sh
 
 # Multi-PHP version testing (RECOMMENDED for releases)
 composer docker:test-all        # Test all PHP versions (8.1-8.4) via Docker
@@ -46,16 +46,16 @@ vendor/bin/phpunit --testsuite=Unit      # Unit tests only
 vendor/bin/phpunit --testsuite=Fast      # Fast tests (excludes stress)
 
 # Additional validation commands
-php ./scripts/validate-psr12.php    # PSR-12 validation (standalone)
-php ./scripts/switch-psr7-version.php --check  # Check PSR-7 version
+php ./scripts/quality/validate-psr12.php    # PSR-12 validation (standalone)
+php ./scripts/utils/switch-psr7-version.php --check  # Check PSR-7 version
 
 # Pre-commit and release
 ./scripts/pre-commit             # Run pre-commit validations
-./scripts/prepare_release.sh 1.1.3  # Prepare release for version 1.1.3
-./scripts/release.sh            # Create release after preparation
+./scripts/release/prepare_release.sh 1.1.3  # Prepare release for version 1.1.3
+./scripts/release/release.sh            # Create release after preparation
 
 # Quality validation (recommended before commits)
-./scripts/quality-check.sh       # Comprehensive quality validation (uses CI tests)
+./scripts/quality/quality-check.sh       # Comprehensive quality validation (uses CI tests)
 ./scripts/pre-push              # Pre-push validation (includes integration tests)
 
 # CI/CD specific commands
@@ -266,11 +266,11 @@ $app->get('/users', 'UserController@index'); // TypeError!
 
 ## Development Workflow
 
-1. Before committing, run `./scripts/pre-commit` or `./scripts/validate_all.sh`
+1. Before committing, run `./scripts/pre-commit` or `./scripts/validation/validate_all.sh`
 2. All tests must pass before pushing changes
 3. Static analysis must pass at Level 9
 4. Code style must comply with PSR-12
-5. For releases, use `./scripts/prepare_release.sh` followed by `./scripts/release.sh`
+5. For releases, use `./scripts/release/prepare_release.sh` followed by `./scripts/release/release.sh`
 
 ### Array Callable Testing (v1.1.4)
 When implementing array callable routes, verify compatibility:

README.md

@@ -577,7 +577,7 @@ php scripts/switch-psr7-version.php 2
 composer update
 
 # Validar o projeto
-./scripts/validate_all.sh
+./scripts/validation/validate_all.sh
 ```
 
 Veja a [documentação completa sobre PSR-7](docs/technical/compatibility/psr7-dual-support.md) para mais detalhes.

composer.json

@@ -133,8 +133,7 @@
             "@phpstan",
             "@test"
         ],
-        "fix:psr12-lines": "./scripts/fix-psr12-lines.sh",
-        "precommit:install": "./scripts/setup-precommit.sh",
+        "precommit:install": "./scripts/utils/setup-precommit.sh",
         "precommit:test": "./scripts/pre-commit",
         "prepush:validate": [
             "@phpstan",
@@ -147,8 +146,8 @@
             "@test",
             "@cs:check"
         ],
-        "validate:docs": "./scripts/validate-docs.sh",
-        "validate:project": "php scripts/validate_project.php",
+        "validate:docs": "./scripts/validation/validate-docs.sh",
+        "validate:project": "php scripts/validation/validate_project.php",
         "examples:basic": "php examples/example_basic.php",
         "examples:auth": "php examples/example_auth.php",
         "examples:auth-simple": "php examples/example_auth_simple.php",
@@ -165,11 +164,11 @@
         "benchmark": "./benchmarks/run_benchmark.sh",
         "benchmark:quick": "./benchmarks/run_benchmark.sh -q",
         "benchmark:simple": "php benchmarks/SimpleBenchmark.php",
-        "docker:test-all": "./scripts/test-all-php-versions.sh",
-        "docker:test-quality": "./scripts/test-all-php-versions.sh --with-quality",
-        "ci:validate": "./scripts/ci-validation.sh",
-        "quality:gate": "./scripts/quality-gate.sh",
-        "quality:metrics": "./scripts/quality-metrics.sh"
+        "docker:test-all": "./scripts/testing/test-all-php-versions.sh",
+        "docker:test-quality": "./scripts/testing/test-all-php-versions.sh --with-quality",
+        "ci:validate": "./scripts/quality/quality-check.sh",
+        "quality:gate": "./scripts/quality/quality-check.sh",
+        "quality:metrics": "./scripts/quality/quality-check.sh"
     },
     "config": {
         "optimize-autoloader": true,

docs/MIGRATION_GUIDE.md

@@ -31,8 +31,8 @@
 - [ ] **Test consolidated scripts** work correctly
 
 #### ✅ Recommended Actions:
-- [ ] **Use consolidated scripts** (`scripts/quality-check.sh`)
-- [ ] **Adopt automatic versioning** (`scripts/version-bump.sh`)
+- [ ] **Use consolidated scripts** (`scripts/quality/quality-check.sh`)
+- [ ] **Adopt automatic versioning** (`scripts/release/version-bump.sh`)
 - [ ] **Read versioning guide** ([docs/VERSIONING_GUIDE.md](VERSIONING_GUIDE.md))
 
 ### 📖 Additional Resources

docs/README.md

@@ -46,8 +46,8 @@ Welcome to the complete documentation for **PivotPHP Core v1.1.4** - a high-perf
 Complete infrastructure optimization and automation:
 ```bash
 # Scripts reduced from 25 to 15 (40% reduction)
-scripts/quality-check.sh    # Consolidated validation
-scripts/version-bump.sh     # Automatic version management
+scripts/quality/quality-check.sh    # Consolidated validation
+scripts/release/version-bump.sh     # Automatic version management
 ```
 
 ### 📦 **Automatic Version Management**  

docs/VERSIONING_GUIDE.md

@@ -113,22 +113,22 @@ O PivotPHP Core inclui um script automatizado para gerenciar versões:
 
 ```bash
 # Incrementar PATCH (1.1.4 → 1.1.5)
-scripts/version-bump.sh patch
+scripts/release/version-bump.sh patch
 
 # Incrementar MINOR (1.1.4 → 1.2.0)  
-scripts/version-bump.sh minor
+scripts/release/version-bump.sh minor
 
 # Incrementar MAJOR (1.1.4 → 2.0.0)
-scripts/version-bump.sh major
+scripts/release/version-bump.sh major
 
 # Visualizar próxima versão sem aplicar
-scripts/version-bump.sh minor --dry-run
+scripts/release/version-bump.sh minor --dry-run
 
 # Fazer bump sem criar commit/tag
-scripts/version-bump.sh patch --no-commit
+scripts/release/version-bump.sh patch --no-commit
 
 # Fazer bump sem criar tag (mas com commit)
-scripts/version-bump.sh minor --no-tag
+scripts/release/version-bump.sh minor --no-tag
 ```
 
 ### O que o Script Faz Automaticamente:
@@ -145,7 +145,7 @@ scripts/version-bump.sh minor --no-tag
 
 ```bash
 # Cenário: Correção de bug de segurança
-$ scripts/version-bump.sh patch
+$ scripts/release/version-bump.sh patch
 
 ℹ️  Versão atual: 1.1.4
 ℹ️  Nova versão: 1.1.5
@@ -180,7 +180,7 @@ Confirma o bump de 1.1.4 para 1.1.5? (y/N): y
 - [ ] Cobertura de testes ≥30% (`composer test:coverage`)
 - [ ] Testes de segurança passando (`composer test:security`)
 - [ ] Performance ≥30K ops/sec (`composer benchmark`)
-- [ ] Validação completa (`scripts/quality-check.sh`)
+- [ ] Validação completa (`scripts/quality/quality-check.sh`)
 
 #### ✅ Documentação:
 - [ ] CHANGELOG.md atualizado
@@ -249,13 +249,13 @@ git checkout main
 git merge feature/new-middleware
 
 # Execute validações
-scripts/quality-check.sh
+scripts/quality/quality-check.sh
 ```
 
 ### 3. Versionamento
 ```bash
 # Para nova funcionalidade (MINOR)
-scripts/version-bump.sh minor
+scripts/release/version-bump.sh minor
 
 # Resultado: 1.1.4 → 1.2.0
 ```
@@ -279,9 +279,9 @@ git push origin main --tags
 - [Contributing Guidelines](../CONTRIBUTING.md)
 
 ### Scripts Relacionados:
-- `scripts/version-bump.sh` - Gerenciamento de versões
-- `scripts/prepare_release.sh` - Preparação para release
-- `scripts/quality-check.sh` - Validação de qualidade
+- `scripts/release/version-bump.sh` - Gerenciamento de versões
+- `scripts/release/prepare_release.sh` - Preparação para release
+- `scripts/quality/quality-check.sh` - Validação de qualidade
 
 ### Comunidade:
 - [Discord PivotPHP](https://discord.gg/DMtxsP7z)