Dokümantasyon

blight, yerel makineniz ile CI/CD ortamları arasındaki sürüm ve ortam kaymasını tespit eden bir PHP CLI aracıdır. Yerel build'inizin neden geçip CI'ın neden başarısız olduğunu tam olarak öğrenmek için tek bir komut çalıştırın.

Giriş

Ortam uyumsuzluğundan kaynaklanan CI hatalarının çoğu, build sunucusuna ulaşana kadar görünmez. blight, yerel ortamınızı GitHub Actions loglarıyla gerçek zamanlı olarak karşılaştırır — PHP sürüm uyumsuzluklarını, eksik Node.js'i ve ENV değişken kaymasını push etmeden önce ortaya çıkarır.

• GitHub Actions log dosyalarını hatalar, uyarılar ve başarısız adımlar için ayrıştırın
• Yerel PHP, Node.js ve ENV durumunu CI'ın kullandığıyla karşılaştırın
• Uyumsuzlukları KRİTİK, UYARI veya BİLGİ olarak sınıflandırın
• Etkileşimli terminal tabloları veya makine tarafından okunabilir JSON olarak çıktı alın

Kurulum

Klonlayın ve yerel olarak çalıştırın

git clone https://github.com/blight-dev/blight.git
cd blight
composer install
php bin/blight --version

Composer global kurulum (Packagist'te yayınlandıktan sonra)

composer global require blight/blight
blight --version

Gereksinimler: PHP 8.2+, Composer 2.x, ext-json

Hızlı Başlangıç

CI uyumsuzluğunu yakalamanın en hızlı yolu:

php bin/blight info

php bin/blight parse --log /path/to/github-actions.log

php bin/blight compare --log /path/to/github-actions.log

php bin/blight report

blight info

$ php bin/blight info
blight.dev – Local Environment Inspector
=========================================
PHP Version   8.2.0
Node Version  20.11.0
OS            Linux x86_64
Branch        main / abc1234
DATABASE_URL  [REDACTED]

blight parse

$ php bin/blight parse --log examples/ci-major-mismatch.log
Steps: Set up PHP ✓, Set up Node.js ✓, Run tests ✗
Errors (2): PHP Fatal error in Util.php:42, exit code 255
Summary: 3 steps, 1 failed, 2 errors

blight compare

┌──────────┬─────────────────┬───────────┬────────┬─────────────────────────────────────┐
│ Severity │ Key             │ Local     │ CI     │ Message                             │
├──────────┼─────────────────┼───────────┼────────┼─────────────────────────────────────┤
│ CRITICAL │ PHP Version     │ 8.2.0     │ 7.4.33 │ Major version mismatch — will fail  │
│ WARNING  │ Node.js Version │ not found │ 18.1.0 │ CI uses Node.js, not installed here │
└──────────┴─────────────────┴───────────┴────────┴─────────────────────────────────────┘

blight report

blight history Paid

blight init

$ php bin/blight init
? API key (leave blank for free plan): blight_pro_xxxxxxxxx
? Default repo name: my-app
? Enable Slack alerts? No
✔ Created .blight.json

Yapılandırma — .blight.json

blight, geçerli dizinde bir .blight.json dosyası arar. blight init ile veya manuel olarak oluşturun:

{
  "api_key": "blight_pro_xxxxxxxxxxxxxxxx",
  "repo": "my-app",
  "alerts": {
    "slack_webhook": "https://hooks.slack.com/services/...",
    "discord_webhook": ""
  }
}

Çıktı Formatları

Tüm komutlar yapılandırılmış makine tarafından okunabilir çıktı için --output json'ı destekler. Betik yazma, CI entegrasyonu veya panolar için kullanışlıdır.

{
  "command": "compare",
  "repo": "my-app",
  "timestamp": "2026-04-09T12:00:00Z",
  "mismatches": [
    {
      "severity": "CRITICAL",
      "key": "PHP Version",
      "local": "8.2.0",
      "ci": "7.4.33",
      "message": "Major PHP version mismatch"
    }
  ],
  "summary": { "critical": 1, "warning": 0, "info": 0 }
}

Sessiz Mod (-q)

Tek satırlık özet almak için herhangi bir komuta -q ekleyin. Kabuk betikleri ve CI pipeline'ları için idealdir.

$ php bin/blight compare --log ci.log -q
CRITICAL: 1, WARNING: 1, Total: 2

$ php bin/blight parse --log ci.log -q
Errors: 2, Warnings: 0, Failed steps: 1

Webhook Bildirimleri Paid

blight, bir compare uyumsuzluk bulduğunda her seferinde webhook bildirimi gönderebilir. Slack ve Discord'u destekler (JSON POST kabul eden herhangi bir servis).

.blight.json üzerinden yapılandırın

{
  "api_key": "blight_pro_xxxxxxxxxxxxxxxx",
  "repo": "my-app",
  "alerts": {
    "slack_webhook": "https://hooks.slack.com/services/T.../B.../xxx",
    "discord_webhook": "https://discord.com/api/webhooks/..."
  }
}

Veya compare ile satır içi geçirin

php bin/blight compare --log ci.log \
  --alert slack \
  --webhook-url https://hooks.slack.com/services/...

GitHub Actions Entegrasyonu

blight, .github/workflows/ci.yml'de kullanıma hazır bir GitHub Actions pipeline'ı ile gelir. Her push ve pull request'te çalışır; lint, statik analiz ve blight'ın kendi dogfood adımlarını kapsar.

name: CI

on:
  push:
  pull_request:

jobs:
  build:
    name: PHP ${{ matrix.php-version }}
    runs-on: ubuntu-latest
    strategy:
      matrix:
        php-version: ["8.2"]

    steps:
      - uses: actions/checkout@v4

      - name: Set up PHP
        uses: shivammathur/setup-php@v2
        with:
          php-version: ${{ matrix.php-version }}

      - name: Validate composer.json
        run: composer validate --strict

      - name: Cache Composer packages
        uses: actions/cache@v4
        with:
          path: vendor
          key: ${{ runner.os }}-composer-${{ hashFiles('composer.lock') }}

      - name: Install dependencies
        run: composer install --no-interaction --prefer-dist

      - name: Lint PHP syntax
        run: find src/ -name "*.php" -print0 | xargs -0 -n1 php -l

      - name: PHPStan static analysis
        run: vendor/bin/phpstan analyse --no-progress --error-format=github

      - name: blight — parse sample log (dogfood)
        continue-on-error: true
        run: php bin/blight parse --log examples/ci-sample.log

      - name: blight — compare local vs CI sample (dogfood)
        continue-on-error: true
        run: php bin/blight compare --log examples/ci-sample.log

blight'ı kendi CI'ınızda kullanma

blight'ı mevcut herhangi bir GitHub Actions iş akışında kayma tespit adımı olarak kullanmak için gerçek CI logunu indiren ve compare çalıştıran bir adım ekleyin:

- name: Detect environment drift with blight
  run: |
    php bin/blight compare --log "${{ runner.temp }}/ci-run.log" -q
  continue-on-error: true

Örnek Log Formatı

blight, deponuzun Actions sekmesinden indirilen GitHub Actions log dosyalarını ayrıştırır. Ayrıştırıcı belirli desenleri arar:

examples/ dizini test için kullanabileceğiniz iki referans log içerir:

• examples/ci-sample.log — Başarısız bir test adımı ve hata satırları içeren gerçekçi 7 adımlı log
• examples/ci-major-mismatch.log — PHP 7.4 ile 8.x arasındaki büyük sürüm uyumsuzluğunu gösteren log

php bin/blight parse --log examples/ci-sample.log
php bin/blight compare --log examples/ci-major-mismatch.log

Pre-push Git Hook

blight'ı bir Git pre-push hook'una bağlayarak push etmeden önce CI kaymasını yakalayın. En son CI logunu kaydedin ve her push'ta otomatik olarak karşılaştırın:

#!/bin/sh
# blight pre-push hook — abort if CRITICAL drift is found
LOG="$HOME/.blight/last-ci.log"
if [ -f "$LOG" ]; then
  RESULT=$(php bin/blight compare --log "$LOG" -q 2>&1)
  echo "$RESULT"
  if echo "$RESULT" | grep -q "CRITICAL: [1-9]"; then
    echo "blight: CRITICAL environment drift detected. Fix before pushing."
    exit 1
  fi
fi
exit 0

chmod +x .git/hooks/pre-push

PHPStan Entegrasyonu

blight, seviye 5'te statik analiz için PHPStan kullanır. Yapılandırma, proje kökündeki phpstan.neon'da bulunur:

includes:
    - phpstan-baseline.neon

parameters:
    level: 5
    paths:
        - src/

phpstan-baseline.neon dosyası, kod tabanındaki önceden var olan hataları temel alır; böylece yalnızca yeni kodun temiz olması gerekir. Hataları düzelttikten sonra temeli yeniden oluşturmak için:

vendor/bin/phpstan analyse --generate-baseline --memory-limit=512M

PHPStan, CI pipeline'ı aracılığıyla her push'ta otomatik olarak çalışır ve --error-format=github kullanarak doğrudan GitHub pull request'lerinde ek açıklamalar çıkarır.

Çok Dil Desteği

blight İngilizce, Türkçe ve Basitleştirilmiş Çince çıktıyı destekler. Tercih ettiğiniz dili CLI bayrağı, yapılandırma dosyası veya ortam değişkeni aracılığıyla ayarlayın.

Kullanım

php bin/blight info --lang tr
php bin/blight compare --log ci.log --lang zh

{
    "lang": "tr"
}

BLIGHT_LANG=tr php bin/blight info

Öncelik Sırası

1. --lang CLI bayrağı
2. .blight.json "lang" alanı
3. BLIGHT_LANG ortam değişkeni
4. Varsayılan: en (İngilizce)

Desteklenen Diller

Ücretsiz Plan

• Depo başına 5 analiz
• 1 depo
• Tüm komutlar kullanılabilir
• Geçmiş son 5 kayıtla sınırlı
• JSON geçmiş dışa aktarma yok

Ücretli Plan

• Sınırsız analiz
• Sınırsız depo
• Filtrelemeli tam geçmiş
• JSON geçmiş dışa aktarma
• Slack ve Discord webhook bildirimleri
• Öncelikli destek

Ücretli özellikleri etkinleştirmek için API anahtarınızı .blight.json'a veya blight init aracılığıyla ayarlayın.