Blast radius nedir: bir pull request diff’in dışında neye dokunur

Blast radius ne demek?

Terim altyapı mühendisliğinden geliyor ve bir arızanın ne kadar yayıldığını anlatıyor. AWS’nin hücre tabanlı mimari kılavuzuna göre sistemi birbirinden yalıtılmış hücrelere bölmek blast radius’u küçültür. Kılavuz bunun yalnızca trafikte değil, yeni bir özelliği ya da bir hata düzeltmesini canlıya alırken de işe yaradığını söylüyor (kaynak).

Kod incelemesinde soru daha dar: bu pull request’in değiştirdiği kodu, pull request’in dışında kim çağırıyor, kim import ediyor? Bir fonksiyonun dönüş tipi değiştiyse onu kullanan her yer etkilenir. İnceleyen kişi de karar verirken bu dosyaları hesaba katmak zorunda. Aynı konu “change impact analysis” (değişiklik etki analizi) adıyla da aranıyor.

Bu yazıda etki alanını en yakın halkayla sınırlıyoruz: değişen dosyayı doğrudan çağıran ya da import eden dosyalar. Böyle bir diyagramı yalnızca gerçek oklarla çizmek için dört kural var.

Diff’te görünmeyen dosyalar

Bir pull request’i açtığınızda GitHub size değişen dosyaları ve satırları gösterir. Değişen kodu kullanan ama kendisi değişmeyen dosyalar o ekranda yoktur; onları inceleyen kişinin hatırlaması gerekir.

Gerçek bir örneğe bakalım: requests kütüphanesinin 7441 numaralı pull request’i iki dosyayı değiştiriyor, _types.py ve models.py. Diff’te yalnızca bu ikisi var. Pull request’in son commit’indeki kodu taradığımızda, dışarıdaki 9 dosyanın bu ikisini kullandığını gördük. Örneğin sessions.py ve adapters.py, models.py’deki PreparedRequest sınıfını doğrudan kullanıyor. O sınıftaki bir değişiklik bu iki dosyanın davranışını da değiştirebilir.

Bu sayıyı nasıl bulduğumuzu ve bazı okları neden bilerek çizmediğimizi yazının devamında anlatıyoruz.

Kimin çağırdığını bulmanın üç yaygın yolu

• Metin araması. git grep -w ad, ismin tam kelime olarak geçtiği her satırı bulur (belgesi). Hızlıdır ve kurulum gerektirmez. Ama ismi bir yorum satırında, bir string’de ya da aynı adlı başka bir fonksiyonda da bulur; hangisinin gerçek çağrı olduğunu sizin ayırmanız gerekir.
• Dil sunucusu. Editördeki “Find All References” aslında Language Server Protocol’ün textDocument/references isteğidir: dil sunucusu, imlecin altındaki sembolün projedeki bütün referanslarını bulur (spesifikasyon). Sonuç kesindir ama her seferinde tek bir sembole bakar, ayrıca projenin editörde kurulu olmasını gerektirir. GitHub’ın tarayıcıdaki kod gezintisi ise tree-sitter kullanır. Kendi belgesine göre depodaki bütün tanım ve referansları tarar ve verilen adı taşıyan öğeleri bulur (belgesi). Yani isimle eşleştirir.
• Çağrı grafiği araçları. Python için pyan, JavaScript için madge gibi araçlar bütün deponun grafiğini çıkarır. pyan kendi analizini “oldukça yüzeysel” diye tanımlar (kaynak); madge ise fonksiyon çağrılarını değil, modül bağımlılıklarını çizer (kaynak). İkisi de tek bir pull request’e değil, bütün depoya bakar; çıkan sonuç bir inceleme yorumuna sığmaz.

Bir pull request için gereken şey bu üçünün arasında bir yerde: dil sunucusu kadar kesin, metin araması kadar hızlı ve yalnızca değişen dosyaların çevresine bakan bir diyagram. Bunun yolu ismi değil, import satırını takip etmek.

Gerçek çıktıda bulduğumuz dört yanlış ok

diffox’ta bir pull request’in etki alanını çizen adımı yazarken ilk sürümlerin çıktısını tek tek okuduk ve dört tür yanlış ok bulduk. Her biri için bir kural koyduk:

1. Birden çok yerde tanımlanmış isim. Aynı adlı bir yardımcı fonksiyon üç ayrı araçta tanımlıydı; birini çağıran dosya, ötekini çağırıyormuş gibi çizildi. Kural: bütün ağaçta tam olarak bir kez tanımlanmamış bir isim için ok çizilmez.
2. Deponun ikinci kopyası. Deponun içindeki bir git worktree, bütün ağacın bir kopyasıydı; ilk koşunun bulduklarının üçte ikisi oradan çıktı. Kural: adı noktayla başlayan klasörlere girilmez.
3. İsmi yalnızca anan satır. Bir yorum satırında fonksiyonun adı örnek olarak geçiyordu. Kural: yalnızca kodun kendisi okunur; yorumlar ve string’ler çıkarıldığında geriye bir çağrı ya da import kalmalıdır.
4. Yanlış dosyaya bağlanan import. from werkzeug.exceptions import NotFound satırı, deponun kendi exceptions.py dosyasını çağırıyormuş gibi çizildi, çünkü iki dosyanın adı aynıydı. Kural: ok, yalnızca çağıranın import satırı gerçekten değişen dosyayı gösteriyorsa çizilir. Göreli bir import’un hedefi yoldan hesaplanır; diğerleri ağaçtaki dosyalara bakılarak tek bir dosyaya bağlanır.

Dördüncü kuralın bir bedeli var: import’u takip edilemeyen bir çağıran diyagrama girmez. Go ve Ruby’de import bir isim bağlamaz, bu yüzden bu dillerdeki dosyalardan ok çizilmez. Bir nesne üzerinden çağrılan metot da (obj.x()) bir dosyaya bağlanamaz. Çizilmeyen bir ok okura bir şey kaybettirmez. Yanlış bir ok ise diyagramın geri kalanına duyulan güveni de götürür.

Diyagramı okunur tutmak

Gerçek bir depoda çağıran dosyaların sayısı hızla artar. İki şey diyagramı okunur tutar.

• Testleri dışarıda bırakın. Kendi depomuzda ilk sürümün çizdiği 19 okun 16’sı test dosyalarından geliyordu. “Bu fonksiyonu testleriniz çağırıyor” bilgisi, pull request’i açan kişinin görmesi gereken bir şey değil. Bir dosyanın test olup olmadığını içeriğine değil, yoluna bakarak anlayın: tests/ klasörü, test_*.py, *.test.ts gibi. Bu oran depodan depoya değişir: requests örneğinde testler de sayılsaydı diyagrama yalnızca bir dosya eklenirdi.
• Kutu sayısını sınırlayın ve dışarıda kalanları belirtin. Kırk kutulu bir diyagram okunmaz; sınırlandığını söylemeyen bir diyagram da eksiksiz sanılır. Biz en fazla 8 kutu ve değişen dosya başına en fazla 6 çağıran gösteriyoruz, dışarıda kalanları da sayıyoruz. requests örneğinde 9 dosyanın 6’sı çizildi, kalan 3 dosya diyagramın altında tek cümleyle belirtildi.

Büyük değişikliklerde aramayı hızlandırmak

Çağıranları bulmanın en basit yolu, değişen dosyaların tanımladığı her isim için ağaçtaki her satırda \bİSİM\b aramaktır. Büyük bir değişiklik yüzlerce isim tanımlar; yüzlerce dosyalık bir ağaçta bu, milyonlarca regex araması demektir. Kendi depomuzdaki büyük bir pull request’te bu adım 19,1 milyon arama yaptı ve diyagram sunucuda 20 saniyelik süre sınırına yetişemedi. Süreyi iki değişiklik kısaltır:

1. Önce adayları eleyin. Değişen dosyanın adı bir dosyada ayrı bir kelime olarak hiç geçmiyorsa, o dosya onu import edemez. Çünkü from service.app import x ya da require("./app") gibi her import satırında yolun son parçası ayrı bir kelime olarak geçer. Eski aracımızda bütün ağacı indekslemek 299 dosyada 51 saniye sürüyordu; bu filtre işi 38 dosyaya ve 3,2 saniyeye indirdi, tek bir ok bile kaybolmadan.
2. İsim başına değil, satır başına arayın. Python belgelerine göre \b, bir kelime karakteriyle kelime olmayan bir karakter arasındaki sınırdır (belgesi). Bu yüzden yalnızca kelime karakterlerinden oluşan bir isim için \bİSİM\b, ancak satırdaki kelimelerden biri tam olarak o isimse eşleşir. Her satırda tek bir findall çalıştırmak bütün isimlere aynı anda cevap verir; geriye yalnızca bir küme kesişimi kalır. $foo ya da valid? gibi başka karakterler içeren isimler yine kendi kalıplarıyla aranır.

import re

WORD = re.compile(r"\w+")

def hits(lines, names):
    """Her satırda geçen isimler: isim başına bir regex yerine satır başına tek findall."""
    wanted = set(names)
    for number, line in enumerate(lines, 1):
        found = wanted.intersection(WORD.findall(line))
        if found:
            yield number, found

Ne kadar hız kazandığınız, aranan isim sayısına bağlı. İki yolu aynı ağaçlarda ve aynı makinede ölçtük; ikisi de her seferinde birebir aynı sonucu buldu:

Django’da tek bir büyük dosya değiştiğinde (127 isim) iki yol arasındaki fark küçük. Değişiklik en büyük beş dosyaya yayıldığında (577 isim) satır başına arama 3,9 kat, kendi pull request’imizde (570 isim) ise 8,2 kat daha hızlı. Yani bu değişiklik her incelemeyi hızlandırmaz; isim sayısı arttığında diyagramın süre sınırına yetişmesini sağlar. Darboğazı da tahminle değil, profiler kullanarak bulduk: sürenin çoğu tek bir döngüde geçiyordu.

Diyagram ne zaman hiç çizilmemeli?

Tarama bir süre ya da boyut sınırına takılıp ağacın yarısında durursa, ortaya çıkan sonuç çağıranların bir örneklemi sayılmaz. Okunmamış bir dosyanın diyagramda çağıranı görünmez ve bu “kimse çağırmıyor” gibi okunur. Bu yüzden şu durumlarda diyagram hiç çizilmez:

• Süre doldu. Tarama ve indeksleme belli bir sürede bitmeli; bizde bu süre 20 saniye.
• Değişen dosya okunamadı. Dosya ya çok büyük ya bir symlink ya da normal bir dosya değil.
• Bir sınır aşıldı. Okunan dosya sayısı, toplam boyut ya da aranan isim sayısı eşiği geçti.
• Çağıran yok. Okları olmayan tek bir kutu, kodun yalıtılmış olduğunu ima eder; veri bunu söylemiyor.

Okura hiçbir şey göstermemek, yanlış bir şey göstermekten iyidir. Ama diyagramın neden çizilmediği log’a yazılmalı: hangisinin hata, hangisinin beklenen bir durum olduğunu ancak log söyler.

Diyagramı GitHub’da Mermaid ile göstermek

Diyagramı okura göstermenin en kolay yolu Mermaid. GitHub belgelerine göre diyagramlar issue’larda, tartışmalarda, pull request’lerde, wiki’lerde ve Markdown dosyalarında görüntülenir. Bunun için Mermaid kodunu mermaid dil etiketli bir kod bloğuna yazmanız yeterli (belgesi).

requests örneğinin diyagramı, pull request yorumuna yazıldığı hâliyle:

```mermaid
flowchart LR
  n0["_types.py"]:::changed
  n1("utils.py")
  n2("adapters.py")
  n3("cookies.py")
  n4("sessions.py")
  n5["models.py"]:::changed
  n6("__init__.py")
  n7("exceptions.py")
  n1 -.->|"SupportsItems"| n0
  n2 -.->|"is_prepared"| n0
  n3 -.->|"is_prepared"| n0
  n4 -.->|"is_prepared"| n0
  n6 -.->|"Request, PreparedRequest +1"| n5
  n7 -.->|"Request, PreparedRequest +1"| n5
  n4 -->|"Request, PreparedRequest +1"| n5
  n1 -.->|"Request, PreparedRequest +1"| n5
  n2 -->|"PreparedRequest, Response"| n5
  classDef changed stroke:#3a6b8b,stroke-width:2px
```

Diyagramı okunur kılan üç küçük karar var. Değişen dosyalar ayrı bir çerçeveyle işaretlenir. Okun üstüne kullanılan isimler yazılır; ilk ikisinden sonrakiler “+1” gibi bir sayıyla özetlenir. Değişen dosyayı yalnızca import eden ve doğrudan çağrısı bulunmayan dosyanın oku kesik çizilir. Diyagramın altındaki tek cümle de neyin çizilmediğini söyler.

diffox’ta etki alanı diyagramı

diffox bir pull request’i her incelediğinde bu adımı son commit üzerinde yeniden çalıştırır. Dışarıdan çağıran bulursa özet yorumuna “Neye dokunuyor” başlığıyla bir Mermaid diyagramı ekler. Kurallar bu yazıdakilerle aynı: model yok, yalnızca import’u değişen dosyayı gösteren oklar, test yok, en fazla 8 kutu, 20 saniyelik süre sınırı ve tarama tamamlanmadıysa diyagram da yok. Desteklenen diller Python, JavaScript/TypeScript ve Java. Diyagramı istemiyorsanız konsolun Ayarlar sekmesinden “Değişiklik özeti”ni kapatabilirsiniz.

Diyagram etki alanını gösterir; bir şey bozuluyorsa bunu bulgular söyler. 17 uzman ajandan biri olan Blast Radius ajanı; bozulan çağıranları, değişen API yüzeylerini ve başka dosyaları bozan imza ya da dönüş tipi değişikliklerini arar (nasıl çalıştığını ayrı bir yazıda anlattık).