# Referință pentru CLI

Greph include patru executabile. Toate patru folosesc același motor; diferă prin interfața pe care o expun.

| Binar | Scop |
|---|---|
| `greph` | Căutare nativă în text, căutare AST și rescriere AST |
| `greph-index` | Index de text încălzit, index de fapte AST și căutare AST memorată în cache |
| `rg` | Wrapper de compatibilitate în stilul ripgrep |
| `sg` | Wrapper de compatibilitate în stilul ast-grep |

Toate căile din exemple folosesc `./vendor/bin/<binary>`, care funcționează cu Greph 0.2.3 sau cu o versiune ulterioară instalată ca dependență. Înlocuiți cu `./bin/<binary>` dacă lucrați dintr-o clonă a depozitului.

---

## `greph`

Căutare nativă în text, căutare AST și rescriere AST.

```bash
greph [options] pattern [path...]
greph -p pattern [options] [path...]
greph -p pattern -r replacement [options] [path...]
```

Dacă omiteți o cale, se caută în directorul curent.

### Modul text

Modul implicit. Modelele sunt expresii regulate PCRE2, cu excepția cazului în care este activat `-F`.

```bash
# Regex search
./vendor/bin/greph "function\s+\w+" src

# Fixed-string search
./vendor/bin/greph -F "function" src

# Case-insensitive whole-word with two lines of context
./vendor/bin/greph -F -i -w -C 2 "function" src
```

Formatul de ieșire corespunde celui din `grep -rn`:

```text
src/Greph.php:31:final class Greph
src/Greph.php:36:    public static function walk(...
```

### Modul AST

Se activează cu `-p`. Modelele sunt scrise ca PHP obișnuite, cu metacaracterele `$VAR` și `$$$VARIADIC`. Consultați [Moduri / Căutare AST](https://greph.inline0.dev/ro/docs/modes/ast) pentru gramatica completă a modelelor.

```bash
./vendor/bin/greph -p 'new $CLASS()' src
./vendor/bin/greph -p '$obj->$method($$$ARGS)' src
./vendor/bin/greph -p 'function $name($$$PARAMS): void {}' src
```

### Modul de rescriere

Se activează combinând `-p` cu `-r`. Șablonul de înlocuire folosește aceleași metacaractere ca modelul de căutare; nodurile capturate sunt inserate după nume.

```bash
# Preview only
./vendor/bin/greph -p 'array($$$ITEMS)' -r '[$$$ITEMS]' --dry-run src

# Apply
./vendor/bin/greph -p 'array($$$ITEMS)' -r '[$$$ITEMS]' src

# Confirm each file before writing
./vendor/bin/greph -p 'array($$$ITEMS)' -r '[$$$ITEMS]' --interactive src
```

### Opțiuni

| Opțiune | Semnificație |
|---|---|
| `-F` | Căutare după șir fix (fără expresii regulate) |
| `-i` | Potrivire fără diferențiere între majuscule și minuscule |
| `-w` | Potrivire de cuvinte întregi |
| `-v` | Inversează potrivirea |
| `-c` | Numără potrivirile din fiecare fișier |
| `-l` | Listează numai căile fișierelor care se potrivesc |
| `-L` | Listează numai căile fișierelor care nu se potrivesc |
| `-h` | Ascunde prefixele cu numele fișierelor în modul text |
| `-H` | Afișează întotdeauna prefixele cu numele fișierelor în modul text |
| `-n` | Afișează numerele liniilor (implicit: activat) |
| `-A N` | Afișează N linii după fiecare potrivire |
| `-B N` | Afișează N linii înainte de fiecare potrivire |
| `-C N` | Afișează N linii de context înainte și după fiecare potrivire |
| `-m N` | Oprește după N potriviri pentru fiecare fișier |
| `-j N` | Folosește N lucrători paraleli |
| `-p PATTERN` | Model de căutare AST |
| `-r TEMPLATE` | Șablon de rescriere AST (necesită `-p`) |
| `--glob GLOB` | Include numai fișiere ale căror căi corespund cu GLOB |
| `--type NAME` | Include un alias de tip de fișier (`php`, `js`, `md`, ...) |
| `--type-not NAME` | Exclude un alias de tip de fișier |
| `--lang NAME` | Limbaj AST. Implicit: `php` |
| `--json` | Emite ieșire JSON |
| `--no-ignore` | Ignoră regulile `.gitignore` și `.grephignore` |
| `--hidden` | Include fișiere ascunse |
| `--dry-run` | Afișează rescrierile fără a scrie fișierele |
| `--interactive` | Confirmă fiecare fișier rescris |
| `--help` | Afișează instrucțiunile de utilizare inline |

---

## `greph-index`

Index de text încălzit, index de fapte AST și căutare AST memorată în cache.

```bash
greph-index build [path] [--index-dir DIR]
greph-index refresh [path] [--index-dir DIR]
greph-index search [options] pattern [path...]

greph-index set build [manifest] [--manifest FILE] [--mode MODE] [--index NAME...]
greph-index set refresh [manifest] [--manifest FILE] [--mode MODE] [--index NAME...]
greph-index set stats [manifest] [--manifest FILE] [--mode MODE] [--index NAME...] [--dry-refresh]
greph-index set search [options] pattern [path...]

greph-index ast-index build [path] [--index-dir DIR]
greph-index ast-index refresh [path] [--index-dir DIR]
greph-index ast-index search [options] pattern [path...]

greph-index ast-cache build [path] [--index-dir DIR]
greph-index ast-cache refresh [path] [--index-dir DIR]
greph-index ast-cache search [options] pattern [path...]
```

### Indexul de text

```bash
# Build (full)
./vendor/bin/greph-index build .

# Build with lifecycle policy
./vendor/bin/greph-index build . \
  --lifecycle opportunistic-refresh \
  --auto-refresh-max-files 32 \
  --auto-refresh-max-bytes 1048576

# Refresh (incremental: added, updated, deleted, unchanged)
./vendor/bin/greph-index refresh .

# Query
./vendor/bin/greph-index search -F "function" .
./vendor/bin/greph-index search -i -w "function" .
./vendor/bin/greph-index search -c "function" .
./vendor/bin/greph-index search --trace-plan -F "function" .
./vendor/bin/greph-index search -F "function" . \
  --index-dir core/.greph-index \
  --index-dir plugins/demo/.greph-index \
  --show-index-origin
```

Indexul de text este un depozit încălzit de trigrame și postări de identificatori. În mod implicit, se află în `.greph-index/` din rădăcina indexată.

### Seturi de indexuri

Seturile de indexuri transformă fluxurile de lucru repetate cu mai multe indexuri într-un manifest cu nume:

```bash
./vendor/bin/greph-index set build
./vendor/bin/greph-index set stats --dry-refresh
./vendor/bin/greph-index set search --show-index-origin -F "function" .
./vendor/bin/greph-index set search --mode ast-index 'new $CLASS()' .
./vendor/bin/greph-index set search --mode ast-cache 'array($$$ITEMS)' .
```

Fișierul manifest implicit este `.greph-index-set.json`. Fiecare intrare indică o rădăcină, un mod și un profil al ciclului de viață. `set build` și `set refresh` operează asupra intrărilor activate; `set search` distribuie căutarea între intrările selectate și elimină potrivirile suprapuse.

### Indexul de fapte AST

```bash
./vendor/bin/greph-index ast-index build .
./vendor/bin/greph-index ast-index refresh .
./vendor/bin/greph-index ast-index search 'new $CLASS()' src
./vendor/bin/greph-index ast-index search --trace-plan 'new $CLASS()' src
./vendor/bin/greph-index ast-index search 'new $CLASS()' . \
  --index-dir core/.greph-ast-index \
  --index-dir plugins/demo/.greph-ast-index \
  --show-index-origin
```

Indexul de fapte AST extrage fapte la nivel de nod (apeluri, instanțieri, clase, metode) într-un depozit interogabil. Căutările folosesc O(log n) pentru cheia faptului, apoi sunt verificate în raport cu sursa. În mod implicit, este stocat în `.greph-ast-index/`.

### Cache-ul AST

```bash
./vendor/bin/greph-index ast-cache build .
./vendor/bin/greph-index ast-cache refresh .
./vendor/bin/greph-index ast-cache search 'array($$$ITEMS)' src
./vendor/bin/greph-index ast-cache search --trace-plan 'array($$$ITEMS)' src
```

Cache-ul AST stochează arborii analizați pe disc, astfel încât căutările să sară complet peste analizator. În mod implicit, este stocat în `.greph-ast-cache/`.

### Opțiuni

Opțiunile de căutare în text corespund setului de opțiuni `greph` (`-F`, `-i`, `-w`, `-v`, `-c`, `-l`, `-L`, `-A`, `-B`, `-C`, `-m`, `--glob`, `--type`, `--type-not`, `--json`, `--no-ignore`, `--hidden`).

Opțiuni suplimentare:

| Opțiune | Semnificație |
|---|---|
| `--index-dir DIR` | Folosește un director de index încălzit diferit de cel implicit. Poate fi repetată pentru căutare și statistici cu mai multe indexuri. |
| `--lifecycle PROFILE` | Politică de construire: `static`, `manual-refresh`, `opportunistic-refresh`, `strict-stale-check` |
| `--auto-refresh-max-files N` | Prag pentru reîmprospătarea oportunistă a fișierelor |
| `--auto-refresh-max-bytes N` | Prag pentru reîmprospătarea oportunistă a octeților |
| `--manifest FILE` | Încarcă un manifest de set de indexuri. Implicit: `.greph-index-set.json` |
| `--mode MODE` | Limitează operațiile setului la `text`, `ast-index` sau `ast-cache` |
| `--index NAME` | Limitează operațiile setului la o intrare de manifest cu nume. Poate fi repetată. |
| `--show-index-origin` | Prefixează ieșirea încălzită cu mai multe indexuri sau cu seturi cu numele intrării de index corespunzătoare |
| `--trace-plan` | Emite diagnosticele planificatorului încălzit în `stderr` |
| `--dry-refresh` | În `stats`, raportează ce ar face o căutare încălzită fără a modifica nimic |
| `--lang NAME` | Limbaj AST pentru căutările `ast-index` / `ast-cache`. Implicit: `php` |
| `-j N`, `--jobs N` | Lucrători pentru scanările AST |
| `-l`, `--files-with-matches` | Listează numai căile fișierelor care se potrivesc (modul AST) |
| `--strict-parse` | Eșuează la erorile de analiză în loc să le omită |
| `--fallback MODE` | Comportament când lipsește indexul: `fail` (implicit) sau `scan` |
| `--help` | Afișează instrucțiunile de utilizare inline |

---

## `rg`

Wrapper de compatibilitate în stilul ripgrep. Acceptă cele mai utilizate opțiuni ripgrep. Suprafața verificată este publicată în [matricea de funcționalități](https://greph.inline0.dev/ro/docs/advanced/feature-matrix).

```bash
rg [options] pattern [path...]
rg --files [options] [path...]
```

### Exemple

```bash
./vendor/bin/rg -F "function" src
./vendor/bin/rg --json -F "function" src
./vendor/bin/rg --files src
./vendor/bin/rg --files --type php .
./vendor/bin/rg --type-not js -F "function" .
```

### Opțiuni acceptate

| Opțiune | Semnificație |
|---|---|
| `-F`, `--fixed-strings` | Căutare după șir fix |
| `-i`, `--ignore-case` | Căutare fără diferențiere între majuscule și minuscule |
| `-w`, `--word-regexp` | Căutare după cuvinte întregi |
| `-v`, `--invert-match` | Inversează potrivirile |
| `-c`, `--count` | Numără liniile care se potrivesc |
| `-l`, `--files-with-matches` | Listează fișierele care se potrivesc |
| `--files-without-match` | Listează fișierele care nu se potrivesc |
| `-I`, `--no-filename` | Ascunde prefixele cu numele fișierelor |
| `-H`, `--with-filename` | Afișează întotdeauna prefixele cu numele fișierelor |
| `-n`, `--line-number` | Afișează numerele liniilor |
| `-A N`, `--after-context N` | Afișează N linii după fiecare potrivire |
| `-B N`, `--before-context N` | Afișează N linii înainte de fiecare potrivire |
| `-C N`, `--context N` | Afișează N linii înainte și după fiecare potrivire |
| `-m N`, `--max-count N` | Oprește după N potriviri pentru fiecare fișier |
| `-j N`, `--threads N` | Folosește N lucrători paraleli |
| `-e P`, `--regexp P` | Model de căutare |
| `-L`, `--follow` | Urmează legăturile simbolice |
| `--glob GLOB` | Include numai fișiere ale căror căi corespund cu GLOB |
| `--type NAME` | Include un tip de fișier |
| `--type-not NAME` | Exclude un tip de fișier |
| `--json` | Emite evenimente ripgrep în stilul JSON |
| `--no-ignore` | Ignoră regulile `.gitignore` și `.grephignore` |
| `--hidden` | Include fișiere ascunse |
| `--files` | Listează fișierele candidate în loc să caute |
| `--help` | Afișează instrucțiunile de utilizare inline |

---

## `sg`

Wrapper de compatibilitate în stilul ast-grep. Acceptă cele mai utilizate opțiuni ast-grep. Suprafața verificată este publicată în [matricea de funcționalități](https://greph.inline0.dev/ro/docs/advanced/feature-matrix).

```bash
sg run --pattern PATTERN [options] [path...]
sg scan -p PATTERN [options] [path...]
sg rewrite -p PATTERN -r TEMPLATE [options] [path...]
```

`run` este verbul canonic ast-grep. `scan` și `rewrite` sunt aliasuri disponibile doar în wrapper, care reflectă utilizarea obișnuită. Funcționează și o invocare fără argumente (`sg --pattern ... .`), pentru o căutare unică.

### Exemple

```bash
./vendor/bin/sg run --pattern 'array($$$ITEMS)' src/App.php
./vendor/bin/sg run --pattern 'array($$$ITEMS)' --rewrite '[$$$ITEMS]' src/App.php
./vendor/bin/sg run --pattern 'array($$$ITEMS)' --rewrite '[$$$ITEMS]' --update-all src/App.php
./vendor/bin/sg run --json --pattern 'dispatch($EVENT)' src/App.php
./vendor/bin/sg scan -p 'array($$$ITEMS)' src/App.php
./vendor/bin/sg rewrite -p 'array($$$ITEMS)' -r '[$$$ITEMS]' --dry-run src/App.php
```

### Opțiuni acceptate

| Opțiune | Semnificație |
|---|---|
| `-p`, `--pattern PATTERN` | Model AST |
| `-r`, `--rewrite TEMPLATE` | Șablon de rescriere |
| `-l`, `--lang NAME` | Limbaj AST. Implicit: `php` |
| `-j`, `--threads N` | Folosește N lucrători paraleli |
| `-i`, `--interactive` | Confirmă fiecare rescriere |
| `-U`, `--update-all` | Aplică rescrierile fără confirmare |
| `--files-with-matches` | Afișează numai căile fișierelor cu potriviri |
| `--json[=STYLE]` | Emite ieșire JSON. STYLE = `pretty`, `stream` sau `compact` |
| `--no-ignore [MODE]` | Ignoră regulile de ignorare ale depozitului |
| `--hidden` | Include fișiere ascunse |
| `--glob GLOB`, `--globs GLOB` | Include numai fișiere ale căror căi corespund cu GLOB |
| `--type NAME` | Include un tip de fișier |
| `--type-not NAME` | Exclude un tip de fișier |
| `--dry-run` | Previzualizează rescrierile fără a scrie fișierele |
| `--help` | Afișează instrucțiunile de utilizare inline |

---

## Coduri de ieșire

Greph respectă convențiile grep / ripgrep:

| Cod | Semnificație |
|---|---|
| `0` | A fost găsită cel puțin o potrivire (sau, în cazul rescrierilor, s-a modificat cel puțin un fișier) |
| `1` | Nu s-au găsit potriviri |
| `2` | Eroare de utilizare sau de execuție (argumente nevalide, index lipsă, eroare de analiză în modul `--strict-parse`) |