MLX v0.32.0, type stub içermeyen wheel'ler yayınladı ve testleri bunu hiç fark etmedi

Ne oldu

Temmuz 2026'da MLX, macOS ARM64 için v0.32.0 wheel'lerini yayınladı ve build yüzeysel olarak sağlıklı görünüyordu: wheel hâlâ py.typed dosyasını içeriyordu; bu işaret dosyası, statik type checker'lara bir paketin typing bilgisi taşıdığını söyler. Ancak dev.to'da yayınlanan bir yazıya göre wheel'de hiç .pyi stub dosyası yoktu — önceki sürümle birlikte gelen her stub paketten sessizce kaybolmuştu. Kurulu kütüphaneye karşı kodunu type-check eden kullanıcılar araçlarının bozulduğunu gördü ve bu kaybı işaret eden hiçbir şey yoktu.

Yazı, projenin kendi test süitinin neden yeşil kaldığını da açıklıyor: testler, stub'ların hâlâ mevcut olduğu kaynak ağacına karşı çalışıyor. Wheel ise ayrı bir build adımıyla üretilen ayrı bir artefakt ve standart yayınlama iş akışında, wheel'e giren şeyin depoda bulunanla eşleştiğini doğrulayan hiçbir adım yok. Yaygın araç zincirindeki yüklemeye en yakın kapı olan twine check yalnızca bir README'nin düzgün render edildiğini doğrular.

Tek seferlik değil, tekrarlanan bir arıza

Yazar, yaklaşık bir ay önce neredeyse aynı nitelikte bir olaya dikkat çekiyor: OpenSpace'den bir build edilmiş dağıtım, takip edilen host_skills/ dizinini sessizce düşürmüş ve pip ile kuran herkesin entegrasyonlarını bozmuştu. İki hatanın kök nedeni aynı: kimse bitmiş artefaktı incelemedi. Build backend'leri, MANIFEST.in hataları ve package-data yanlış yapılandırmaları depo, sdist ve wheel arasındaki herhangi bir adımda dosya düşürebilir — yazının çerçevelediği gibi bunlar üç ayrı artefakttır — ve sorun yalnızca kurulumdan sonra, bir modül veya stub eksik çıktığında görünür hale gelir.

wheeltruth depoyu değil, wheel'i inceler

Bu tür kırılmaları kullanıcılardan öğrenmekten bıkan yazar, build edilmiş dağıtımları doğrudan denetleyen yalnızca stdlib kullanan bir komut satırı aracı olan wheeltruth'u geliştirdi. Bir wheel verildiğinde, araç RECORD manifestinin eşleşen sha256 hash'leri ve boyutlarla eksiksiz olduğunu, console ve GUI script giriş noktalarının wheel içinde gerçekten bulunan modüllere çözüldüğünü, stub dosyalarının bir paket genelinde tutarlı olduğunu — MLX örneğindeki gibi kısmen düşürülmüş bir kümeyi işaretler — ve METADATA'daki ad ile sürümün wheel dosya adıyla uyumlu olduğunu doğrular.

Bir wheel ve bir sdist birlikte verildiğinde, araç ikisini karşılaştırır ve birinde takip edilen ancak diğerinde bulunmayan dosyaları raporlar; bu, OpenSpace senaryosunu kapsar. Tamlık için iki mod daha vardır: biri pyproject.toml veya setup.cfg içinde bildirilen paketleri wheel'in gerçek içeriğine karşı doğrular, bir smoke modu ise bir wheel'i kullan-at bir virtual environment'a kurar ve her üst düzey modülü import eder. Exit kodları CI için tasarlandı — temizse sıfır, sorun bulunursa bir — böylece araç, build'den hemen sonra bir doğrulama adımı olarak yerleştirilebilir.

Sınırlar ve PyPI ilk 300'üne yönelik bir tarama

Yazar, v0.1'in sınırları hakkında açık sözlü: araç sorunları rapor ediyor ama build yapılandırmasını onarmıyor, beklenen dosya buluşsal yöntemleri alışılmadık düzenlerde yanlış pozitifler üretebiliyor ve stub denetimi yalnızca iç tutarlılığı zorunlu kılıyor, çünkü araç önceki bir sürümün neyi içerdiğini bilemez. Yayınlamadan önce yazar, aracı kendi dağıtımına karşı çalıştırdı ve temiz bir sonuç aldı. PyPI'nın en çok indirilen 300 wheel'ine yönelik daha geniş bir tarama, sıfır hash uyuşmazlığı, sıfır RECORD boşluğu ve sıfır metadata uyuşmazlığı buldu — ekosistemin tepesi ayakta kaldı ve yazar bundan bozuk wheel istatistiği üretmeyi reddediyor. Ortaya çıkan 45 işaret ise elle kontrol edildiğinde, wheeltruth'un kendisinde üç hatayı ortaya çıkaran yanlış pozitiflerdi; bunlar vendored RECORD birleştirme, entry-point re-export'ları ve aşırı agresif stub denetimleriyle ilgiliydi; düzeltmeler v0.2 için planlandı.

Neden önemli

Yeşil bir test süiti, kullanıcıların gerçekte kurduğu artefakt hakkında hiçbir şey söylemez. CI kaynak ağacına karşı çalışırken release pipeline, sdist veya depo ile hiç karşılaştırmadan bir wheel'i yüklediğinde, gerilemeler sessizce yayınlanır — ve typed kütüphaneler için stub'lar genel arayüzün parçasıdır, dolayısıyla tüm testler geçse bile bunları kaybetmek bir breaking change'tir. Build sonrası bir doğrulama adımı — ister wheeltruth ister eşdeğer bir denetim — bu boşluğu birkaç saniyelik build süresiyle kapatır. Aynı zamanda araç hijyenine iyi bir örnektir: yazar, denetleyiciyi başkalarının dağıtımlarında kullanmaya güvenmeden önce kendi çıktısına karşı test etmiş ve sonra gerçek dünyaya yönelik bir taramayla aracın kendi hatalarını bulmuştur.