Develop

.github/workflows/ci.yml

@@ -0,0 +1,48 @@
+name: CI
+
+# ARFA 1.3 / KaririCode Spec V4.0 — Unified CI Pipeline
+# Runs on every push and PR targeting main or develop.
+# Full pipeline: cs-fixer → phpstan (L9) → psalm → phpunit (pcov)
+# Zero tolerance: any tool failure blocks the merge.
+
+on:
+  push:
+    branches: [main, develop]
+  pull_request:
+    branches: [main, develop]
+  workflow_dispatch:
+
+jobs:
+  quality:
+    name: Quality Pipeline (ARFA 1.3)
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      # PHP 8.4 + pcov (mandatory driver per ARFA 1.3 §Testing)
+      - uses: shivammathur/setup-php@v2
+        with:
+          php-version: '8.4'
+          extensions: mbstring, xml, openssl
+          coverage: pcov
+
+      # Pure dependency install — no scripts to avoid environment pollution
+      - name: Install dependencies
+        run: composer install --no-interaction --prefer-dist --no-progress --no-scripts
+
+      # Bootstrap kcode.phar from the official KaririCode release
+      - name: Install kcode (KaririCode Devkit)
+        run: |
+          wget -q https://github.com/KaririCode-Framework/kariricode-devkit/releases/latest/download/kcode.phar
+          chmod +x kcode.phar
+          sudo mv kcode.phar /usr/local/bin/kcode
+
+      # Generate .kcode/ configs: phpunit.xml.dist, phpstan.neon, psalm.xml, etc.
+      - name: Initialize devkit (.kcode/ generation)
+        run: kcode init
+
+      # cs-fixer → phpstan (L9) → psalm → phpunit
+      # Exit code ≠ 0 fails the job (zero-tolerance policy)
+      - name: Run full quality pipeline
+        run: kcode quality

.github/workflows/code-quality.yml

@@ -0,0 +1,208 @@
+name: Code Quality
+
+# ARFA 1.3 / KaririCode Spec V4.0 — Parallel Quality Gates
+# Runs 5 parallel jobs with a quality-summary gate job.
+# Triggers: main, develop, feature branches, PRs, and manual dispatch.
+
+on:
+  push:
+    branches:
+      - main
+      - develop
+      - 'feature/**'
+  pull_request:
+    branches:
+      - main
+      - develop
+  workflow_dispatch:
+
+jobs:
+  # ============================================================================
+  # DEPENDENCY VALIDATION (Spec V4.0 — zero-dep contract)
+  # Validates that composer.json is valid and platform requirements are met.
+  # Dotenv v4 mandates: zero external runtime dependencies.
+  # ============================================================================
+  dependencies:
+    name: Dependency Validation
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: shivammathur/setup-php@v2
+        with:
+          php-version: '8.4'
+          tools: composer:v2
+          coverage: none
+
+      - name: Validate composer.json
+        run: composer validate --strict --no-check-lock
+
+      - name: Install dependencies
+        run: composer install --prefer-dist --no-progress --no-scripts
+
+      - name: Check platform requirements
+        run: composer check-platform-reqs
+
+  # ============================================================================
+  # SECURITY AUDIT (ARFA 1.3 — resilience pillar)
+  # Uses native composer audit — no deprecated security-checker.
+  # ============================================================================
+  security:
+    name: Security Audit
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: shivammathur/setup-php@v2
+        with:
+          php-version: '8.4'
+          tools: composer:v2
+          coverage: none
+
+      - name: Install dependencies
+        run: composer install --prefer-dist --no-progress --no-scripts
+
+      - name: Run composer audit
+        run: composer audit --format=plain
+
+  # ============================================================================
+  # STATIC ANALYSIS (Spec V4.0 S14 — Type Safety)
+  # kcode analyse runs PHPStan Level 9 + Psalm (100% type inference).
+  # Both tools must pass with zero errors — enforced by kcode exit code.
+  # ============================================================================
+  analyse:
+    name: Static Analysis — PHPStan L9 + Psalm
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: shivammathur/setup-php@v2
+        with:
+          php-version: '8.4'
+          extensions: mbstring, xml, openssl
+          coverage: none
+          tools: composer:v2
+
+      - name: Install dependencies
+        run: composer install --prefer-dist --no-progress --no-scripts
+
+      - name: Install kcode
+        run: |
+          wget -q https://github.com/KaririCode-Framework/kariricode-devkit/releases/latest/download/kcode.phar
+          chmod +x kcode.phar
+          sudo mv kcode.phar /usr/local/bin/kcode
+
+      - name: Initialize devkit
+        run: kcode init
+
+      # Runs PHPStan Level 9 then Psalm sequentially — both must pass
+      - name: Run PHPStan + Psalm via kcode
+        run: kcode analyse
+
+  # ============================================================================
+  # CODE STYLE (ARFA 1.3 Naming / Formatting Standards)
+  # kcode cs:fix enforces PSR-12 + PHP 8.4 migrations + KaririCode rules.
+  # --check: dry-run only — fails if any violation exists.
+  # ============================================================================
+  cs-fixer:
+    name: Code Style — PHP CS Fixer
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: shivammathur/setup-php@v2
+        with:
+          php-version: '8.4'
+          extensions: mbstring, xml
+          coverage: none
+          tools: composer:v2
+
+      - name: Install dependencies
+        run: composer install --prefer-dist --no-progress --no-scripts
+
+      - name: Install kcode
+        run: |
+          wget -q https://github.com/KaririCode-Framework/kariricode-devkit/releases/latest/download/kcode.phar
+          chmod +x kcode.phar
+          sudo mv kcode.phar /usr/local/bin/kcode
+
+      - name: Initialize devkit
+        run: kcode init
+
+      - name: Check code style (dry-run)
+        run: kcode cs:fix --check
+
+  # ============================================================================
+  # UNIT & INTEGRATION TESTS (ARFA 1.3 §Testing — Zero Tolerance)
+  # pcov is the mandatory driver (performance + accuracy over Xdebug).
+  # Requires: 0 failures, 0 errors, 0 warnings, 0 risky tests.
+  # Target: 205 tests / 396 assertions (dotenv v4 baseline).
+  # ============================================================================
+  tests:
+    name: PHPUnit — 205 Tests (pcov)
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: shivammathur/setup-php@v2
+        with:
+          php-version: '8.4'
+          extensions: mbstring, xml, openssl
+          coverage: pcov
+          tools: composer:v2
+
+      - name: Install dependencies
+        run: composer install --prefer-dist --no-progress --no-scripts
+
+      - name: Install kcode
+        run: |
+          wget -q https://github.com/KaririCode-Framework/kariricode-devkit/releases/latest/download/kcode.phar
+          chmod +x kcode.phar
+          sudo mv kcode.phar /usr/local/bin/kcode
+
+      - name: Initialize devkit
+        run: kcode init
+
+      - name: Run tests with coverage (pcov)
+        run: kcode test --coverage
+
+  # ============================================================================
+  # QUALITY SUMMARY — Gate job (if: always())
+  # Aggregates all job results and fails the workflow if any check failed.
+  # Posts a markdown summary to the GitHub Actions run.
+  # ============================================================================
+  quality-summary:
+    name: Quality Summary
+    runs-on: ubuntu-latest
+    needs: [dependencies, security, analyse, cs-fixer, tests]
+    if: always()
+
+    steps:
+      - name: Post quality summary
+        run: |
+          echo "## KaririCode Dotenv — Quality Report (ARFA 1.3)" >> "$GITHUB_STEP_SUMMARY"
+          echo "" >> "$GITHUB_STEP_SUMMARY"
+          echo "| Check | Result |" >> "$GITHUB_STEP_SUMMARY"
+          echo "|-------|--------|" >> "$GITHUB_STEP_SUMMARY"
+          echo "| Dependency Validation | ${{ needs.dependencies.result }} |" >> "$GITHUB_STEP_SUMMARY"
+          echo "| Security Audit | ${{ needs.security.result }} |" >> "$GITHUB_STEP_SUMMARY"
+          echo "| Static Analysis (PHPStan L9 + Psalm) | ${{ needs.analyse.result }} |" >> "$GITHUB_STEP_SUMMARY"
+          echo "| Code Style (CS Fixer) | ${{ needs.cs-fixer.result }} |" >> "$GITHUB_STEP_SUMMARY"
+          echo "| PHPUnit Tests (205 / pcov) | ${{ needs.tests.result }} |" >> "$GITHUB_STEP_SUMMARY"
+
+          if [ "${{ needs.security.result }}" != "success" ] || \
+             [ "${{ needs.analyse.result }}" != "success" ] || \
+             [ "${{ needs.cs-fixer.result }}" != "success" ] || \
+             [ "${{ needs.tests.result }}" != "success" ]; then
+            echo "" >> "$GITHUB_STEP_SUMMARY"
+            echo "❌ One or more quality gates failed. Merge blocked." >> "$GITHUB_STEP_SUMMARY"
+            exit 1
+          fi
+
+          echo "" >> "$GITHUB_STEP_SUMMARY"
+          echo "✅ All quality gates passed — ARFA 1.3 compliant." >> "$GITHUB_STEP_SUMMARY"