Δοκιμές

Το Greph επικυρώνεται με τρία επίπεδα δοκιμών:

1. Δοκιμές μονάδων για μεμονωμένα στοιχεία (αναλυτές, διασχίσεις, κωδικοποιητές, επιλογές).
2. Σύνολο παλινδρόμησης oracle που συγκρίνει τη μοναδική έξοδο του Greph με τα κανονικά δυαδικά αρχεία grep, ripgrep και ast-grep σε ένα σταθερό σύνολο σεναρίων.
3. Πίνακας δυνατοτήτων με βάση ελέγχους που επιβεβαιώνει τις επαληθευμένες δυνατότητες των περιβλημάτων rg και sg.

Το CI εκτελείται σε κάθε push στο main και σε κάθε αίτημα έλξης (.github/workflows/ci.yml). Εκτελεί ελέγχους προτύπων κώδικα (composer cs), στατική ανάλυση (composer analyse), τις σουίτες δοκιμών μονάδων και ενσωμάτωσης του PHPUnit (composer test) και το composer audit στο PHP 8.4. Το σύνολο oracle (composer test:oracle) δεν αποτελεί μέρος του CI, ενώ ο πίνακας δυνατοτήτων αναδημιουργείται χειροκίνητα με το php bin/feature-matrix. Η σουίτα PHPUnit περιέχει μια δοκιμή που δημιουργεί τον πίνακα με τα εργαλεία upstream rg και sg δηλωμένα ως μη διαθέσιμα και ελέγχει τη δομή της αναφοράς, ώστε να μην αποτυγχάνει όταν παλινδρομεί ένας μεμονωμένος έλεγχος.

Εργασία από κλώνο

Όλα όσα περιλαμβάνει αυτή η σελίδα απαιτούν κλώνο του αποθετηρίου. Επειδή το πακέτο Composer 0.2.3 περιέχει μόνο το src/ και τα τέσσερα εκτελέσιμα χρόνου εκτέλεσης, τα tests/, scenarios/, benchmarks/ και τα σενάρια ανάπτυξης στο bin/ δεν περιλαμβάνονται σε αυτό.

git clone https://github.com/inline0/greph
cd greph
composer install

Εκτέλεση των δοκιμών

# PHPUnit unit and integration suites
composer test

# Oracle regression corpus
composer test:oracle

# Static analysis
composer analyse

# Coding standards
composer cs
composer cs:fix

# Full release-grade verification (analyse + cs + test + test:oracle)
composer verify

Το composer verify είναι απαραίτητη προϋπόθεση για κάθε έκδοση. Αν αποτύχει, η αλλαγή δεν είναι ολοκληρωμένη.

Το μοντέλο oracle

Το Greph ακολουθεί ένα μοντέλο επαλήθευσης με βάση oracle. Για κάθε σενάριο εκτελούνται τρεις εντολές:

1. Oracle: grep, ripgrep ή ast-grep, με έξοδο καταγεγραμμένη για το σύνολο σεναρίων.
2. Πραγματικό αποτέλεσμα: Greph, με έξοδο καταγεγραμμένη για το ίδιο σύνολο.
3. Συγκριτής: δομημένη σύγκριση που ελέγχει ισοδυναμία γραμμή προς γραμμή ή σημασιολογικά.

Αν το Greph διαφωνεί με το oracle, το Greph είναι λανθασμένο. Αν τα grep και rg διαφωνούν μεταξύ τους, το σενάριο καταγράφει τη διαφωνία στο oracle_disagreement, κατονομάζει το εργαλείο που ακολουθεί το Greph στο greph_follows και ορίζει τη σύγκριση με το άλλο εργαλείο ως skip. Στο σύνολο υπάρχουν και οι δύο κατευθύνσεις.

Τα σενάρια κειμένου συγκρίνονται με τα grep και rg, ενώ τα σενάρια AST και επανεγγραφής με το sg. Η έξοδος oracle καταγράφεται μία φορά και δεσμεύεται στον φάκελο oracle/ κάθε σεναρίου, επομένως μια συνηθισμένη εκτέλεση χρειάζεται μόνο το PHP· τα εξωτερικά εργαλεία χρειάζονται μόνο για την καταγραφή ή ανανέωση της εξόδου oracle.

Η υλοποίηση βρίσκεται στο tests/Oracle/ και τα σενάρια βρίσκονται στα scenarios/text/, scenarios/ast/, scenarios/rewrite/ και scenarios/edge/.

Διάταξη σεναρίου

Κάθε σενάριο είναι ένας αυτοτελής φάκελος:

scenarios/text/literal-simple/
├── scenario.json     # name, category, pattern, flags, path
├── setup/            # corpus to search through
├── oracle/           # captured oracle output (grep.txt, rg.txt, rg.json, ...)
├── actual/           # captured greph output (generated, git-ignored)
└── reports/          # comparison results (generated, git-ignored)

Το scenario.json δηλώνει το μοτίβο, τις σημαίες και τη διαδρομή αναζήτησης. Ένα προαιρετικό αντικείμενο expectations ορίζει τη λειτουργία σύγκρισης ανά oracle (exact, semantic ή skip)· χωρίς αυτό, τα σενάρια κειμένου συγκρίνουν ακριβώς τα grep και rg και σημασιολογικά το rg JSON, ενώ τα σενάρια AST και επανεγγραφής συγκρίνονται με το sg.

Εκτέλεση ενός σεναρίου

Το αποθετήριο διαθέτει ένα μικρό σύνολο CLI για εργασία με μεμονωμένα σενάρια. Είναι εργαλεία ανάπτυξης, όχι σημεία εισόδου χρόνου εκτέλεσης: βρίσκονται δίπλα στα εκτελέσιμα χρόνου εκτέλεσης στο bin/, αλλά δεν αποτελούν μέρος του πακέτου Composer. Καθένα δέχεται το όνομα του σεναρίου σε σχέση με το scenarios/.

# Capture oracle output for a scenario (needs grep and rg, or sg)
./bin/oracle text/literal-simple

# Run greph against a scenario, capture its output
./bin/actual text/literal-simple

# Diff oracle vs actual
./bin/compare text/literal-simple

# Full pipeline: oracle (only if missing) -> actual -> compare
./bin/test-scenario text/literal-simple

# Recapture the oracle output first
./bin/test-scenario text/literal-simple --refresh

Εκτέλεση της πλήρους σουίτας παλινδρόμησης

# All scenarios (the same as composer test:oracle)
./bin/test-regression

# Filter by category
./bin/test-regression --category text
./bin/test-regression --category ast
./bin/test-regression --category rewrite
./bin/test-regression --category edge

# Print only failures and the summary
./bin/test-regression --fast

# Recapture every oracle before comparing
./bin/test-regression --refresh

Τα σενάρια εκτελούνται πάντα ένα κάθε φορά. Το --jobs N γίνεται δεκτό και εμφανίζεται στη γραμμή σύνοψης, αλλά δεν εκτελεί τίποτα παράλληλα (#7). Σε έναν νέο κλώνο, τα text/no-ignore και text/explicit-file-input αποτυγχάνουν, επειδή τα αρχεία δεδομένων δοκιμών τους στο setup/vendor/ δεν έχουν δεσμευτεί (#6).

Η σουίτα παλινδρόμησης είναι η πύλη για νέες συμπεριφορές. Μια νέα σημαία, μια νέα οριακή περίπτωση ή μια διόρθωση σφάλματος απαιτεί ένα σενάριο που καταγράφει την αναμενόμενη συμπεριφορά με βάση oracle.

Αναφορά συμμόρφωσης

./bin/verify-compliance

Το verify-compliance δεν εκτελεί τίποτα από μόνο του. Διαβάζει τα αρχεία oracle, αποτελεσμάτων και αναφοράς που άφησε πίσω της η τελευταία εκτέλεση σεναρίου και εμφανίζει ποια σενάρια περνούν, ποια αποτυγχάνουν και ποια δεν έχουν ακόμη αναφορά. Εκτελέστε πρώτα το ./bin/test-regression. Το --output report.json γράφει επίσης την αναφορά ως JSON. Αυτή είναι η κατάλληλη εντολή όταν θέλετε να μάθετε «είναι έτοιμος για έκδοση ο τρέχων κλάδος;».

Ροή ανάπτυξης με δοκιμές πρώτα

Κατά την προσθήκη μιας δυνατότητας:

1. Γράψτε έναν φάκελο σεναρίου με το σύνολο δεδομένων και τις σημαίες που ασκούν τη νέα συμπεριφορά.
2. Εκτελέστε το ./bin/oracle <scenario> για να καταγράψετε την έξοδο του κανονικού εργαλείου.
3. Υλοποιήστε τη δυνατότητα στο src/.
4. Εκτελέστε το ./bin/test-scenario <scenario> για να επαληθεύσετε ότι το Greph συμφωνεί με το oracle.
5. Εκτελέστε το ./bin/test-regression --fast για να βεβαιωθείτε ότι δεν παλινδρόμησε κάτι άλλο.
6. Εκτελέστε το composer verify πριν από τη δέσμευση.

Κατά τη διόρθωση ενός σφάλματος:

1. Καταγράψτε την αποτυχημένη είσοδο ως σενάριο.
2. Επιβεβαιώστε ότι το oracle παράγει την αναμενόμενη έξοδο.
3. Επιβεβαιώστε ότι το Greph δεν την παράγει.
4. Διορθώστε το σφάλμα.
5. Επιβεβαιώστε ότι το Greph συμφωνεί πλέον με το oracle.
6. Εκτελέστε το composer verify.

Το σενάριο παραμένει μόνιμα στο σύνολο, ώστε το σφάλμα να μην μπορεί να επανεμφανιστεί χωρίς να αποτύχουν το composer test:oracle (και το composer verify).