# Prechádzač súborov

Každý režim Greph (text, AST, prepisovanie, indexovaný text, indexované AST, AST z vyrovnávacej pamäte, obal `rg`, obal `sg`) začína prechodom stromom súborov a vytvorením `Greph\Walker\FileList`. Prechádzač sa zdieľa, takže všade platia rovnaké príznaky a správanie.

## Predvolené správanie

Prechádzač v predvolenom nastavení:

- Rekurzívne prechádza každý adresár pod zadanými cestami.
- Na každej úrovni rešpektuje pravidlá `.gitignore` a `.grephignore` vrátane vnorených prepísaní pravidiel a negácií.
- Preskakuje adresár `.git`.
- Preskakuje skryté súbory a adresáre (všetko, čo začína na `.`).
- Preskakuje binárne súbory (rozpozná ich podľa nulových bajtov v prvých 512 bajtoch súboru).
- Preskakuje súbory väčšie ako 10 MiB.
- Nenasleduje symbolické odkazy.

## Príznaky na prepísanie nastavení

| Príznak | Účinok |
|---|---|
| `--no-ignore` | Prestať rešpektovať `.gitignore` a `.grephignore` |
| `--hidden` | Zahrnúť skryté súbory a adresáre |
| `--type NAME` | Zahrnúť iba súbory zodpovedajúce pomenovanému aliasu typu |
| `--type-not NAME` | Vylúčiť súbory zodpovedajúce pomenovanému aliasu typu |
| `--glob GLOB` | Zahrnúť iba súbory, ktorých cesty zodpovedajú vzoru GLOB. Možno opakovať. |

Rovnaké možnosti sú programovo dostupné aj cez `Greph\Walker\WalkOptions`.

```php
use Greph\Greph;
use Greph\Walker\FileTypeFilter;
use Greph\Walker\WalkOptions;

$files = Greph::walk('src', new WalkOptions(
    respectIgnore: false,
    includeHidden: true,
    fileTypeFilter: new FileTypeFilter(['php']),
    globPatterns: ['src/**/*.php'],
));
```

## Aliasy typov súborov

Greph obsahuje malú sadu pomenovaných typov súborov. Každý alias sa rozbalí na zoznam prípon:

| Alias | Prípony |
|---|---|
| `css` | `css`, `sass`, `scss` |
| `html` | `htm`, `html`, `phtml` |
| `js` | `cjs`, `js`, `mjs` |
| `json` | `json` |
| `md` | `markdown`, `md` |
| `php` | `inc`, `php`, `php3`, `php4`, `php5`, `php7`, `php8`, `phpt`, `phtml` |
| `txt` | `txt` |
| `ts` | `ts`, `tsx` |
| `xml` | `xml` |
| `yaml` | `yaml`, `yml` |

Úplný zoznam sa nachádza v `Greph\Walker\FileTypeFilter::TYPE_MAP`.

## Sémantika .gitignore

Greph implementuje porovnávanie gitignore v čistom PHP. Sémantika zodpovedá `git check-ignore`:

- Vzory sa vyhodnocujú vzhľadom na adresár, v ktorom sa nachádzajú.
- Vnorené súbory `.gitignore` prepisujú nadradené pravidlá.
- Negácia (`!pattern`) znova zahrnie predtým vylúčenú cestu.
- Záverečné `/` obmedzuje vzor na adresáre.
- Úvodné `/` ukotvuje vzor v adresári súboru `.gitignore`.
- `**` zodpovedá ľubovoľnému počtu segmentov cesty.

`.grephignore` používa rovnakú syntax a nadväzuje na `.gitignore`. Je to správne miesto na vylúčenia špecifické pre nástroj, ktoré nechcete vo správe verzií.

Implementácia sa nachádza v `Greph\Walker\GitignoreFilter`.

## Rozpoznávanie binárnych súborov

Prechádzač kontroluje prvých 512 bajtov každého súboru, či neobsahujú nulové bajty. Ak sa nejaké nájdu, súbor sa považuje za binárny a preskočí sa. Zachytí sa tým bežný prípad, keď repozitár obsahuje obrázky, archívy alebo skompilované artefakty v indexovanom adresári.

Ak chcete aj tak vyhľadávať v binárnych súboroch, nastavte `skipBinaryFiles: false` v príslušnom objekte `Options`. CLI momentálne neponúka príznak pre toto nastavenie; použite fasádu.

## Symbolické odkazy

Symbolické odkazy sa predvolene nenasledujú. Ak ich chcete nasledovať, nastavte `followSymlinks: true` (alebo odovzdajte `-L` / `--follow` obalu `rg`). Prechádzač sleduje navštívené adresáre, takže slučky symbolických odkazov nespôsobia nekonečnú rekurziu.

## Maximálna veľkosť súboru

Súbory väčšie ako `maxFileSizeBytes` (predvolene 10 MiB) sa preskakujú. Chráni to skenovanie pred náhodným načítaním 1 GB súboru denníka do pamäte. Ak potrebujete zahrnúť väčšie vstupy, upravte limit v objekte `Options`.

## Prečo vlastný prechádzač

Greph by mohlo využívať `glob()` alebo `RecursiveDirectoryIterator`, no ani jeden nástroj neimplementuje sémantiku gitignore, nerozumie `.grephignore` a ani jeden sa čisto neintegruje s fondom pracovníkov. Jednorazové napísanie prechádzača a jeho zdieľanie medzi režimami navyše znamená, že každý režim používa presne rovnaké pravidlá filtrovania. To je zásadné pre stratégiu testovania riadeného oracle: porovnávať s `grep`, `ripgrep` a `ast-grep` možno iba pri prechode tou istou sadou súborov ako tieto nástroje.