Dokümantasyon / Geliştirici modu

Değişikliği doğrulamak

ivralo verify, projenizin kendi kontrollerini bir değişiklik üzerinde en ucuzundan başlayarak çalıştırır ve ilk hatada durur. Ajanlar da bir değişikliğe bitti demeden önce aynı pipeline'ı çalıştırır. Komut, IVRALO.md'deki roller, testlerin nasıl seçildiği ve hataların JUnit ve SARIF raporlarından nasıl okunduğu bu sayfada.

Komut

ivralo verify                       # git'in HEAD'den beri değişti dediği şeyler
ivralo verify src/app/totals.py     # bu dosyalar
ivralo verify --scope full          # bir pull request'ten önce bütün test komutu

Seçenek	Etkisi
`[paths]`	Değişen dosyalar; verilmezse git'e göre `HEAD`'den beri değişenler
`--scope targeted`	Varsayılan: değişikliğe göre seçilen testler, ardından bir halka daha geniş
`--scope full`	Diğer kontrollerden sonra tanımlı test komutunun tamamı
`--yes`, `-y`	Onay isteyecek komutları onaylar
`--trust`	Çalıştırmadan önce bu klasörü güvenilir olarak işaretler ve bunu hatırlar

Rapor stdout'a yazılır. Terminalde, shell politikasına göre onay gerektiren komutlar listelenir ve tek seferde onaylanır. Bir pipe içinde ise --yes verilmedikçe bu komutlar reddedilir.

Çıkış kodu	Anlamı
`0`	Pipeline'ı hiçbir şey durdurmadı
`1`	Bir aşama başarısız oldu ve pipeline durdu
`2`	Doğrulama yapılamıyor: klasör bir repo değil ya da hiç komut tanımlanmamış

Bir tur içinde ajanlar aynı pipeline'ı verify_changes aracıyla çağırır. Bu aracın diyaloğu, çalıştıracağı komutları bir runs satırında listeler.

Roller: `# Commands` bölümü

Pipeline, IVRALO.md'nin # Commands bölümündeki dört rolü şu sırayla çalıştırır:

# Commands

- format: `uv run ruff format --check .`
- lint: `uv run ruff check .`
- types: `uv run mypy`
- test: `uv run pytest -q`

Rol	Not
`format`	Komutun kontrol eden hâlini tanımlayın (`ruff format --check .`, `prettier --check .`). Komut yazıldığı gibi çalışır, dolayısıyla dosyaları yeniden yazan bir hâli dosyalarınızı değiştirir. Böyle olursa rapor değişen dosyaları listeler
`lint`	Herhangi bir linter
`types`	Herhangi bir type checker
`test`	Önce değişikliğin dokunduğu testler, sonra bir halka daha geniş

Pipeline başarısız olan ilk aşamada durur ve hangisi olduğunu yazar (stopped at lint). Tanımlamadığınız bir rol "not declared" olarak raporlanır ve atlanır: ivralo hiçbir zaman komut tahmin etmez. Bölümdeki diğer adlar (build, e2e) aşama sayılmaz.

Bir komutu tanımlamak ona izin vermek anlamına gelmez. Her komut, bir run_shell komutu gibi yine shell politikasına göre değerlendirilir: yalnızca okuma yapan ya da izin verilmiş bir komut hemen çalışır, onay gerektiren bir komut diyalog açar, reddedilen bir komut hiçbir zaman çalışmaz. Güvenmediğiniz bir klasörde tanımlı komutlar reddedilir.

Yollar için yer tutucular

Seçilen test yolları test komutunuzun sonuna eklenir. Yolları başka bir yerde bekleyen bir test çalıştırıcı için {paths} yer tutucusu içeren bir test-paths satırı tanımlayın:

- test: `make test`
- test-paths: `make test FILES="{paths}"`

Sembol düzenlemelerinden sonra çalışan formatter da aynı şekilde bir format-paths satırı kullanır (Kod analizi).

Hangi testler çalışır

Seçim yalnızca repo'nuzdaki dosyalara bakar. Adında test kelimesi geçen her dosya test dosyası sayılır (test_totals.py, totals_test.go, money.test.ts, FooTest.java).

1. halka: değişen bir dosyanın adını taşıyan testler, o dosyayı anan testler ve sizin değiştirdiğiniz testler.
2. halka: bu testlerin bulunduğu klasörler.
Hiçbir testle eşleşmeyen bir değişiklikte, örneğin bir config dosyasında, seçim en yakın test klasörüne, oradan da test komutunun tamamına genişler. Hiçbir zaman test atlanmaz.

Raporun her satırında seçimin neden o genişlikte olduğu ve hangi test alanlarının dışarıda kaldığı yazar. Rapor, çalışanı hiçbir zaman olduğundan büyük göstermez: önce targeted tests passed (12 selected ...), sonra wider ring passed, sonra the suite was not run. the suite passed ifadesini yalnızca --scope full kullanır.

Test dosyalarının adında test kelimesi geçmeyen projelerde (*.spec.ts, bir spec/ ağacı) hiçbir şey seçilemez. Bu yüzden her değişiklikte test komutunun tamamı çalışır.

Kararsız (flaky) testler

Başarısız olup tek bir tekrar çalıştırmada geçen bir test aşaması flaky olarak işaretlenir. İlk çalışmanın çıktısı saklanır ve pipeline devam eder. İkinci kez başarısız olursa bu gerçek bir hatadır. ivralo kararsız testi raporlar, düzeltmeye çalışmaz.

Bir hatayı okumak: `# Reports`

Başarısız bir test çalışmasının çıktısı binlerce satır olabilir ve sonuna bakınca çoğu zaman hangi testin patladığı görünmez. Bu yüzden başarısız bir aşamanın çıktısı önce okunur ve rapor bulunan sonuçla başlar:

what failed in test (targeted):
  tests: 2 failed, 1 error, 38 passed, 3 skipped (report:junit)
  failures (report:junit):
    1. tests.test_totals::test_refund - AssertionError: assert 7 == 5
       at tests/test_totals.py:22
  in the project: src/ledger/totals.py:18, tests/test_totals.py:22 (paths)
  outcome: exit 1 · 2 failed, 1 error, 38 passed in 0.31s (outcome)

Bilgi üç yerden okunur ve ivralo araçlarınızın hiçbirini adıyla tanımaz:

Komutlarınızın yazdığı raporlar. Bir komut JUnit XML ya da SARIF dosyası yazıyorsa, bu dosyayı # Reports altında, her rol için bir tane olmak üzere, repo'ya göre bir yol ya da glob olarak belirtin. ivralo komutunuza hiçbir zaman seçenek eklemez, yani dosyayı komutun kendisinin yazması gerekir.
Çıktıda geçen, projenize ait yollar. git'in listelediği bir dosyayı gösteren her path:line, projenizin bir frame'idir. Bunlar çıktıdaki sırasıyla gösterilir. Kodunuzun bir kütüphaneyi çağırdığı yerdeki, proje dışındaki tek frame de bunlara eklenir.
Son satır: çıkış kodu ve çıktının son satırı.

# Commands

- lint: `uv run ruff check --output-format sarif -o reports/lint.sarif .`
- test: `uv run pytest -q --junitxml=reports/junit.xml`

# Reports

- lint: reports/lint.sarif
- test: reports/junit.xml

Format, dosyanın adından değil içeriğinden anlaşılır. JUnit sayıları ve başarısız her testin fırlattığı hatayı verir. SARIF her bulgunun kuralını, seviyesini, mesajını ve yerini verir. TAP okunmaz.

Bu çalıştırmanın yazmadığı bir rapor (geride kalmış eski bir rapor) ya da eksik, bozuk, boş veya çok büyük bir rapor sayıya dönüşmez, bir note: satırı olarak yazılır. ivralo okuyamadığı bir rapor için hiçbir zaman "0 failed" demez. Komut başarısız olduğu hâlde hiç hata saymayan bir rapor da (örneğin bir collection hatasında) ayrıca belirtilir.