Μετάβαση στο περιεχόμενο

Πίνακας χαρακτηριστικών

Προβολή ως Markdown Επεξεργασία στο GitHub Τεκμηρίωση στο d105217

Ο πίνακας χαρακτηριστικών είναι μια αναφορά που δημιουργείται αυτόματα και καταγράφει, για κάθε υποστηριζόμενη σημαία και συμπεριφορά, αν το εγγενές εργαλείο και το περίβλημα Greph παράγουν ισοδύναμη έξοδο. Αποτελεί την έγκυρη πηγή για ερωτήματα όπως «υποστηρίζει το Greph αυτό;».

Ο πίνακας δημιουργείται ξανά με πραγματικές δοκιμές εντολών σε έναν ντετερμινιστικό χώρο εργασίας δοκιμών. Τα ακατέργαστα στοιχεία βρίσκονται στο FEATURE_MATRIX.json και ο μορφοποιημένος πίνακας στο FEATURE_MATRIX.md.

Υπόμνημα κατάστασης

Κατάσταση Σημασία
Pass Η δοκιμή εκτελέστηκε και συμφώνησε με την αναμενόμενη συμπεριφορά
Fail Η δοκιμή εκτελέστηκε, αλλά δεν ικανοποίησε την αναμενόμενη συμπεριφορά
Unavailable Η εντολή του παρόχου δεν υπήρχε σε αυτό το περιβάλλον

Ενότητες

Ο πίνακας χωρίζεται σε έξι ενότητες:

  1. Επιφάνεια συμβατότητας rg: κάθε δοκιμή εκτελείται τόσο με το upstream δυαδικό αρχείο rg όσο και με το bin/rg. Και τα δύο πρέπει να Pass για να σημειωθεί η γραμμή ως υποστηριζόμενη.
  2. Επιφάνεια συμβατότητας sg: κάθε δοκιμή εκτελείται τόσο με το upstream δυαδικό αρχείο sg όσο και με το bin/sg. Και τα δύο πρέπει να Pass για να σημειωθεί η γραμμή ως υποστηριζόμενη.
  3. Επιφάνεια μόνο για το περίβλημα sg: δοκιμές που στοχεύουν μόνο το bin/sg (πρόσθετες λειτουργίες που διαθέτει το περίβλημα, αλλά όχι το ίδιο το ast-grep).
  4. Εγγενής επιφάνεια greph: δοκιμές που εξετάζουν απευθείας το bin/greph. Δεν υπάρχει upstream εργαλείο για σύγκριση· οι δοκιμές ελέγχουν την αναμενόμενη συμπεριφορά στον χώρο εργασίας δοκιμών.
  5. Επιφάνεια greph με ευρετήριο: δοκιμές που εξετάζουν το bin/greph-index (δημιουργία, ανανέωση και αναζήτηση κειμένου με ενεργό ευρετήριο).
  6. Επιφάνεια βιβλιοθήκης AST με ευρετήριο: δοκιμές που καλούν το PHP API (Greph::buildAstIndex(), Greph::searchAstIndexed(), Greph::buildAstCache(), Greph::searchAstCached()) και ελέγχουν τη δημιουργία, την αναζήτηση και την ανανέωση.

Αναδημιουργία του πίνακα

Κέλυφος
php bin/feature-matrix

Εκτελέστε το από κλωνοποιημένο αποθετήριο με τα rg και sg στο PATH· το bin/feature-matrix δεν αποτελεί μέρος του πακέτου Composer. Δημιουργεί τον χώρο εργασίας δοκιμών, εκτελεί κάθε δοκιμή συμβατότητας με το upstream δυαδικό αρχείο (αν είναι εγκατεστημένο) και με το περίβλημα Greph, καταγράφει το δομημένο αποτέλεσμα και γράφει τα FEATURE_MATRIX.json και FEATURE_MATRIX.md. Περάστε το --stdout για να εμφανιστεί το Markdown χωρίς να γραφτεί κανένα από τα δύο αρχεία.

Τα αρχεία που έχουν ενσωματωθεί στο αποθετήριο δημιουργούνται ξανά χειροκίνητα· το CI δεν τα αναδημιουργεί. Η σουίτα PHPUnit που εκτελεί το CI περιλαμβάνει δοκιμή που δημιουργεί τον πίνακα με τα upstream εργαλεία ως μη διαθέσιμα και ελέγχει τη δομή της αναφοράς, ώστε η αποτυχία μίας μόνο δοκιμής να μην αποτυγχάνει το CI. Αναδημιουργήστε τον πίνακα και ελέγξτε τις διαφορές πριν από μια έκδοση.

Τι ανήκει στον πίνακα και τι στην τεκμηρίωση

Η αναφορά CLI και οι σελίδες Συμβατότητα / rg και Συμβατότητα / sg περιγράφουν την προβλεπόμενη επιφάνεια. Ο πίνακας χαρακτηριστικών καταγράφει την επαληθευμένη επιφάνεια, μαζί με τα ακριβή ορίσματα δοκιμών σε κάθε γραμμή.

Αν κάτι τεκμηριώνεται αλλά λείπει από τον πίνακα, η τεκμηρίωση δεν είναι ενημερωμένη. Αν κάτι υπάρχει στον πίνακα αλλά δεν τεκμηριώνεται, χρειάζεται να συμπληρωθεί η τεκμηρίωση. Τα δύο πρέπει να συμφωνούν.

Παραδείγματα γραμμών

Συμβατότητα rg (απόσπασμα)

Λειτουργία rg bin/rg Σημειώσεις
Αναζήτηση σταθερής συμβολοσειράς Pass Pass Δοκιμή: -F needle single.txt
Αναζήτηση σταθερής συμβολοσειράς χωρίς διάκριση πεζών-κεφαλαίων Pass Pass Δοκιμή: -F -i needle single.txt
Αναζήτηση ολόκληρης λέξης Pass Pass Δοκιμή: -F -w needle words.txt
Φίλτρο glob Pass Pass Δοκιμή: --glob *.php function .
Κρυφά αρχεία Pass Pass Δοκιμή: --hidden -F secret .
Δομημένη έξοδος JSON Pass Pass Δοκιμή: --json -F needle single.txt με σημασιολογία συμβάντων ripgrep-JSON

Συμβατότητα sg (απόσπασμα)

Λειτουργία sg bin/sg Σημειώσεις
Αναζήτηση μοτίβου με run --pattern Pass Pass Δοκιμή: run --pattern array($$$ITEMS) src/App.php
Επανεγγραφή μέσω run --rewrite Pass Pass Δοκιμή: run --pattern array($$$ITEMS) --rewrite [$$$ITEMS] src/App.php
Έξοδος δομημένης ροής JSON Pass Pass Δοκιμή: run --json=stream --pattern dispatch($EVENT) src/App.php
Επανεγγραφή όλων Pass Pass Δοκιμή: run --pattern array($$$ITEMS) --rewrite [$$$ITEMS] --update-all src/App.php

Για τον πλήρη πίνακα, δείτε το FEATURE_MATRIX.md.

Γιατί δοκιμές βάσει ελέγχων

Ένας πίνακας συμβατότητας που συντηρείται χειροκίνητα αποκλίνει. Όλη η αξία των περιβλημάτων είναι η υπόσχεση «αντικαταστήστε το εκεί όπου καλούσατε το rg ή το sg και θα συνεχίσει να λειτουργεί», και ο μόνος τρόπος να τηρηθεί είναι να εκτελούνται πράγματι το upstream εργαλείο και το περίβλημα παράλληλα και να συγκρίνονται οι έξοδοί τους. Ο εκτελεστής δοκιμών κάνει ακριβώς αυτό κάθε φορά που αναδημιουργείται ο πίνακας.