# Filvandrare

Varje läge i Greph (text, AST, omskrivning, indexerad text, indexerad AST, cachad AST, omslag `rg`, omslag `sg`) börjar med att gå igenom filträdet och skapa en `Greph\Walker\FileList`. Vandraren delas mellan lägena, så samma flaggor och beteenden gäller överallt.

## Standardbeteende

Som standard gör vandraren följande:

- Går rekursivt igenom alla kataloger under de angivna sökvägarna.
- Följer reglerna i `.gitignore` och `.grephignore` på alla nivåer, inklusive nästlade åsidosättningar och negationer.
- Hoppar över katalogen `.git`.
- Hoppar över dolda filer och kataloger (allt som börjar med `.`).
- Hoppar över binärfiler (identifieras med null-byte i filens första 512 byte).
- Hoppar över filer som är större än 10 MiB.
- Följer inte symboliska länkar.

## Åsidosättningsflaggor

| Flagga | Effekt |
|---|---|
| `--no-ignore` | Sluta följa `.gitignore` och `.grephignore` |
| `--hidden` | Ta med dolda filer och kataloger |
| `--type NAME` | Ta endast med filer som matchar det angivna typaliaset |
| `--type-not NAME` | Uteslut filer som matchar det angivna typaliaset |
| `--glob GLOB` | Ta endast med filer vars sökvägar matchar GLOB. Kan upprepas. |

Samma alternativ är tillgängliga via `Greph\Walker\WalkOptions` för programmatisk användning.

```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'],
));
```

## Aliaser för filtyper

Greph innehåller en liten uppsättning namngivna filtyper. Varje alias motsvarar en lista med filändelser:

| Alias | Filändelser |
|---|---|
| `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` |

Hela listan finns i `Greph\Walker\FileTypeFilter::TYPE_MAP`.

## Semantik för .gitignore

Greph implementerar gitignore-matchning i ren PHP. Semantiken följer `git check-ignore`:

- Mönster utvärderas relativt katalogen där de finns.
- Nästlade `.gitignore`-filer åsidosätter regler från överordnade kataloger.
- Negation (`!pattern`) tar med en tidigare utesluten sökväg igen.
- Avslutande `/` begränsar ett mönster till kataloger.
- Inledande `/` förankrar ett mönster i katalogen för `.gitignore`.
- `**` matchar valfritt antal sökvägssegment.

`.grephignore` använder samma syntax och är ett lager ovanpå `.gitignore`. Där passar verktygsspecifika undantag som du inte vill ha i versionshanteringen.

Implementationen finns i `Greph\Walker\GitignoreFilter`.

## Binärdetektering

Vandraren kontrollerar filens första 512 byte efter null-byte. Om några finns behandlas filen som binär och hoppas över. Det fångar det vanliga fallet där ett kodarkiv innehåller bilder, arkiv eller kompilerade artefakter i en indexerad katalog.

Om du ändå vill söka i binärfiler anger du `skipBinaryFiles: false` på det aktuella `Options`-objektet. CLI har för närvarande ingen flagga för detta; använd fasaden.

## Symboliska länkar

Symboliska länkar följs inte som standard. Ange `followSymlinks: true` (eller skicka `-L` / `--follow` på omslaget `rg`) för att följa dem. Vandraren håller reda på besökta kataloger så att länkcirklar inte orsakar oändlig rekursion.

## Maximal filstorlek

Filer som är större än `maxFileSizeBytes` (standardvärde 10 MiB) hoppas över. Det skyddar genomsökningar från att av misstag läsa in en loggfil på 1 GB i minnet. Åsidosätt gränsen på `Options`-objektet när du behöver hantera större indata.

## Varför en anpassad vandrare

Greph skulle kunna förlita sig på `glob()` eller `RecursiveDirectoryIterator`, men inget av dem implementerar gitignore-semantik, förstår inte `.grephignore` och integreras inte smidigt med arbetarpoolen. Genom att skriva vandraren en gång och dela den mellan lägena får alla lägen dessutom exakt samma filtreringsregler, vilket är avgörande för den oracle-styrda teststrategin: det enda sättet att jämföra med `grep`, `ripgrep` och `ast-grep` är att gå igenom samma uppsättning filer som de verktygen går igenom.