İçeriğe geç

Özellik Matrisi

Markdown olarak görüntüle GitHub üzerinde düzenle Dokümantasyon: d105217

Özellik matrisi, desteklenen her bayrak ve davranış için yerel aracın ve Greph sarmalayıcısının eşdeğer çıktı üretip üretmediğini kaydeden, oluşturulmuş bir rapordur. “Greph bunu destekliyor mu?” sorularında başvurulacak temel kaynaktır.

Matris, belirleyici bir test çalışma alanında gerçek komut yoklamalarından yeniden oluşturulur. Ham kanıt FEATURE_MATRIX.json içinde, oluşturulan tablo ise FEATURE_MATRIX.md içinde bulunur.

Durum açıklamaları

Durum Anlamı
Pass Yoklama çalıştı ve beklenen davranışla eşleşti
Fail Yoklama çalıştı ancak beklenen davranışı karşılamadı
Unavailable Sağlayıcı komutu bu ortamda mevcut değildi

Bölümler

Matris altı bölüm halinde düzenlenmiştir:

  1. rg Uyumluluk Alanı: her yoklama hem yukarı akıştaki rg ikili dosyasına hem de bin/rg aracına karşı çalıştırılır. Satırın destekleniyor olarak işaretlenmesi için ikisinin de Pass olması gerekir.
  2. sg Uyumluluk Alanı: her yoklama hem yukarı akıştaki sg ikili dosyasına hem de bin/sg aracına karşı çalıştırılır. Satırın destekleniyor olarak işaretlenmesi için ikisinin de Pass olması gerekir.
  3. Yalnızca sg Sarmalayıcısına Özgü Alan: yalnızca bin/sg hedefleyen yoklamalar (sarmalayıcının sunduğu, ast-grep aracının kendisinde bulunmayan ek özellikler).
  4. Yerel greph Alanı: doğrudan bin/greph kullanan yoklamalar. Karşılaştırılacak bir yukarı akış aracı yoktur; yoklamalar, test çalışma alanında beklenen davranışı doğrular.
  5. Dizinlenmiş greph Alanı: bin/greph-index aracını (oluşturma, yenileme ve önbelleği ısınmış metin araması) kullanan yoklamalar.
  6. Dizinlenmiş AST Kitaplığı Alanı: PHP API öğesini (Greph::buildAstIndex(), Greph::searchAstIndexed(), Greph::buildAstCache(), Greph::searchAstCached()) çağıran ve oluşturma, arama ve yenilemeyi denetleyen yoklamalar.

Matrisi yeniden oluşturma

Kabuk
php bin/feature-matrix

Bunu, deponun bir klonundan rg ve sg PATH üzerinde olacak şekilde çalıştırın; bin/feature-matrix, Composer paketinin parçası değildir. Test çalışma alanını oluşturur, her uyumluluk yoklamasını (kuruluysa) yukarı akış ikili dosyasına ve Greph sarmalayıcısına karşı çalıştırır, yapılandırılmış sonucu kaydeder ve hem FEATURE_MATRIX.json hem de FEATURE_MATRIX.md dosyalarını yazar. Herhangi bir dosyayı yazmadan Markdown çıktısını almak için --stdout seçeneğini iletin.

Depodaki dosyalar elle yeniden oluşturulur; CI bunları yeniden oluşturmaz. CI'nın çalıştırdığı PHPUnit paketi, yukarı akış araçlarının kullanılamaz olarak işaretlendiği bir matris oluşturan ve raporun yapısını denetleyen bir test içerir; böylece tek bir yoklamanın başarısız olması CI'yı bozmaz. Sürüm öncesinde matrisi yeniden oluşturup değişiklikleri gözden geçirin.

Matris ile belgelerde neler yer alır?

CLI başvurusu ile Uyumluluk / rg ve Uyumluluk / sg sayfaları amaçlanan alanı açıklar. Özellik matrisi ise her satırın yanında tam yoklama argümanlarıyla doğrulanmış alanı kaydeder.

Belgelenmiş ancak matriste yer almayan bir şey varsa belgeler güncel değildir. Matriste yer alıp belgelenmeyen bir şey varsa belgelere eklenmelidir. İkisi de birbiriyle eşleşmelidir.

Örnek satırlar

rg uyumluluğu (alıntı)

Özellik rg bin/rg Notlar
Sabit dizge araması Geçti Geçti Yoklama: -F needle single.txt
Büyük/küçük harfe duyarsız sabit dizge araması Geçti Geçti Yoklama: -F -i needle single.txt
Tam sözcük araması Geçti Geçti Yoklama: -F -w needle words.txt
Glob filtresi Geçti Geçti Yoklama: --glob *.php function .
Gizli dosyalar Geçti Geçti Yoklama: --hidden -F secret .
Yapılandırılmış JSON çıktısı Geçti Geçti JSON ripgrep olay semantiğini kullanan yoklama: --json -F needle single.txt

sg uyumluluğu (alıntı)

Özellik sg bin/sg Notlar
run --pattern ile desen arama Geçti Geçti Yoklama: run --pattern array($$$ITEMS) src/App.php
run --rewrite üzerinden yeniden yazma Geçti Geçti Yoklama: run --pattern array($$$ITEMS) --rewrite [$$$ITEMS] src/App.php
Yapılandırılmış JSON akış çıktısı Geçti Geçti Yoklama: run --json=stream --pattern dispatch($EVENT) src/App.php
Tümünü güncelleme ile yeniden yazma Geçti Geçti Yoklama: run --pattern array($$$ITEMS) --rewrite [$$$ITEMS] --update-all src/App.php

Tam tablo için FEATURE_MATRIX.md sayfasına bakın.

Yoklamaya dayalı yaklaşımın nedeni

Elle sürdürülen bir uyumluluk tablosu zamanla güncelliğini yitirir. Sarmalayıcıların temel amacı “eskiden rg veya sg çağırdığınız yere bunları koyun, çalışmaya devam etsinler”dir ve bu vaadi yerine getirmenin tek yolu, yukarı akış aracını ve sarmalayıcıyı yan yana gerçekten çalıştırıp sonuçları karşılaştırmaktır. Yoklama çalıştırıcısı, matris her yeniden oluşturulduğunda tam olarak bunu yapar.