# Ominaisuusmatriisi

Ominaisuusmatriisi on luotu raportti, joka kirjaa jokaisen tuetun valitsimen ja toiminnon osalta, tuottavatko natiivi työkalu ja Greph-kääre saman tulosteen. Se on luotettava lähde kysymyksille, kuten ”tukeeko Greph tätä?”.

Matriisi luodaan uudelleen suorittamalla todellisia komentokokeita deterministisessä testiympäristössä. Raakatulokset ovat tiedostossa [`FEATURE_MATRIX.json`](https://github.com/inline0/greph/blob/main/FEATURE_MATRIX.json), ja muotoiltu taulukko on tiedostossa [`FEATURE_MATRIX.md`](https://github.com/inline0/greph/blob/main/FEATURE_MATRIX.md).

## Tilaselitteet

| Tila | Merkitys |
|---|---|
| `Pass` | Koe suoritettiin ja tulos vastasi odotettua toimintaa |
| `Fail` | Koe suoritettiin, mutta tulos ei vastannut odotettua toimintaa |
| `Unavailable` | Tarjoajan komentoa ei ollut saatavilla tässä ympäristössä |

## Osiot

Matriisi on jaettu kuuteen osioon:

1. **rg-yhteensopivuus**: kukin koe suoritetaan sekä upstream-version `rg`-ohjelmalla että ohjelmalla `bin/rg`. Molempien on `Pass`, jotta rivi merkitään tuetuksi.
2. **sg-yhteensopivuus**: kukin koe suoritetaan sekä upstream-version `sg`-ohjelmalla että ohjelmalla `bin/sg`. Molempien on `Pass`, jotta rivi merkitään tuetuksi.
3. **Vain sg-kääreen ominaisuudet**: kokeet kohdistuvat vain kohteeseen `bin/sg` (lisäominaisuuksiin, joita kääre tarjoaa mutta joita ast-grep-ohjelmassa ei ole).
4. **Natiivin grephin ominaisuudet**: kokeet kohdistuvat suoraan kohteeseen `bin/greph`. Vertailtavaa upstream-työkalua ei ole, joten kokeet varmistavat odotetun toiminnan testiympäristössä.
5. **Indeksoidun grephin ominaisuudet**: kokeet kohdistuvat kohteeseen `bin/greph-index` (koonti, päivitys ja lämmitetty tekstihaku).
6. **Indeksoidun AST-kirjaston ominaisuudet**: kokeissa kutsutaan PHP API-kirjastoa (`Greph::buildAstIndex()`, `Greph::searchAstIndexed()`, `Greph::buildAstCache()`, `Greph::searchAstCached()`) ja tarkistetaan koonti, haku ja päivitys.

## Matriisin luominen uudelleen

```bash
php bin/feature-matrix
```

Suorita tämä tietovaraston kloonista, jossa `rg` ja `sg` ovat hakemistossa `PATH`; `bin/feature-matrix` ei kuulu Composer-pakettiin. Se luo testiympäristön, suorittaa kunkin yhteensopivuuskokeen upstream-ohjelmalla (jos se on asennettu) ja Greph-kääreellä, tallentaa rakenteiset tulokset ja kirjoittaa sekä tiedoston `FEATURE_MATRIX.json` että tiedoston `FEATURE_MATRIX.md`. Tulosta Markdown antamalla valitsin `--stdout` kirjoittamatta kumpaakaan tiedostoa.

Tietovarastossa olevat tiedostot luodaan uudelleen käsin; CI ei luo niitä uudelleen. CI:n suorittama PHPUnit-testikokoelma sisältää testin, joka luo matriisin niin, että upstream-työkalut merkitään puuttuviksi, ja tarkistaa raportin rakenteen. Näin yhden kokeen epäonnistuminen ei kaada CI:tä. Luo matriisi uudelleen ja tarkista muutokset ennen julkaisua.

## Matriisin ja dokumentaation sisältö

CLI-viite ja sivut [Yhteensopivuus / rg](https://greph.inline0.dev/fi/docs/compatibility/rg) sekä [Yhteensopivuus / sg](https://greph.inline0.dev/fi/docs/compatibility/sg) kuvaavat suunniteltuja ominaisuuksia. Ominaisuusmatriisi tallentaa varmistetut ominaisuudet sekä kunkin rivin tarkat koeparametrit.

Jos dokumentaatiossa kuvattua ominaisuutta ei ole matriisissa, dokumentaatio on vanhentunut. Jos ominaisuus on matriisissa mutta sitä ei ole dokumentoitu, dokumentaatioon on lisättävä tiedot. Näiden tulee vastata toisiaan.

## Esimerkkirivit

### rg-yhteensopivuus (ote)

| Ominaisuus | rg | bin/rg | Huomautukset |
|---|---|---|---|
| Kiinteän merkkijonon haku | Läpäisty | Läpäisty | Koe: `-F needle single.txt` |
| Kirjainkoosta riippumaton kiinteän merkkijonon haku | Läpäisty | Läpäisty | Koe: `-F -i needle single.txt` |
| Kokonaisten sanojen haku | Läpäisty | Läpäisty | Koe: `-F -w needle words.txt` |
| Glob-suodatin | Läpäisty | Läpäisty | Koe: `--glob *.php function .` |
| Piilotetut tiedostot | Läpäisty | Läpäisty | Koe: `--hidden -F secret .` |
| Rakenteinen JSON-tuloste | Läpäisty | Läpäisty | Koe: `--json -F needle single.txt`, jossa käytetään ripgrep-JSON-tapahtumien semantiikkaa |

### sg-yhteensopivuus (ote)

| Ominaisuus | sg | bin/sg | Huomautukset |
|---|---|---|---|
| Hakumallihaku komennolla `run --pattern` | Läpäisty | Läpäisty | Koe: `run --pattern array($$$ITEMS) src/App.php` |
| Uudelleenkirjoitus kohteella `run --rewrite` | Läpäisty | Läpäisty | Koe: `run --pattern array($$$ITEMS) --rewrite [$$$ITEMS] src/App.php` |
| Rakenteinen JSON-virran tuloste | Läpäisty | Läpäisty | Koe: `run --json=stream --pattern dispatch($EVENT) src/App.php` |
| Kaikkien osumien uudelleenkirjoitus | Läpäisty | Läpäisty | Koe: `run --pattern array($$$ITEMS) --rewrite [$$$ITEMS] --update-all src/App.php` |

Katso koko taulukko: [`FEATURE_MATRIX.md`](https://github.com/inline0/greph/blob/main/FEATURE_MATRIX.md).

## Miksi kokeisiin perustuva

Käsin ylläpidetty yhteensopivuustaulukko vanhenee. Kääreiden tarkoitus on, että ne voidaan ottaa suoraan käyttöön vanhojen `rg`- tai `sg`-kutsujen tilalla ja ne toimivat edelleen. Tämä lupaus voidaan pitää vain suorittamalla upstream-työkalu ja kääre rinnakkain ja vertailemalla tuloksia. Koekomentosarja tekee juuri näin aina, kun matriisi luodaan uudelleen.