# CLI

Phasis включва три основни изпълними файла в `bin/`:

- **`bin/phasis`** — изпълнява файлове JavaScript, изчислява изходен код, подаден от командния ред, и извежда AST.
- **`bin/test262`** — изпълнява официалния пакет за съответствие с ECMAScript спрямо Phasis.
- **`bin/wpt`** — изпълнява фикстурите от Web Platform Tests спрямо Phasis (URL, кодиране, Fetch, заглавки, Blob, AbortSignal, потоци и др.).

След `composer require phasis/phasis`, `bin/phasis` и `bin/test262` се свързват от `vendor/bin/`. Оттам работи само `bin/phasis`: за `bin/test262` са нужни подмодулът `test262` git и тестовите класове, които пакетът Composer не включва, а `bin/wpt` изобщо не се доставя. Стартирайте и двете от клонирано копие на хранилището Phasis.

## bin/phasis

```
phasis <file.js> | phasis -e '<source>' | phasis --ast <file.js>
```

Тези три форми съставляват целия интерфейс. Няма REPL, вход от stdin или флаг за модули.

### Изпълнение на файл

```bash
./vendor/bin/phasis script.js
```

Изпълнява `script.js` като класически скрипт. Когато приключи, всичко, което скриптът е записал с `console.log` (както и `console.error`, `console.warn` и др.), се извежда наведнъж към stdout. Ако скриптът хвърли грешка, съобщението се извежда към stderr, а кодът за изход е 1.

Файлът винаги се анализира като класически скрипт, затова файл с `import` / `export` или `await` на най-горно ниво ще завърши със SyntaxError. За да стартирате ES модул, използвайте `Engine::evalAsModule()` от PHP (вижте справката за [API](https://phasis.inline0.dev/bg/docs/api#evalasmodule)) или първо обединете кода.

### Изчисляване на изходен код

```bash
./vendor/bin/phasis -e 'console.log(Math.PI * 2)'
# 6.283185307179586
```

Аргументът се изчислява като цялостен скрипт. Извежда се само резултатът от `console`; стойността на последния израз не се извежда, затова `phasis -e '1 + 2'` не извежда нищо.

### Извеждане на AST

```bash
./vendor/bin/phasis --ast script.js
./vendor/bin/phasis -e 'a + b' --ast
```

Извежда дървото на синтактичния анализ във формат JSON (с отстъп от два интервала). Полезно е за отстраняване на проблеми с анализатора или за изграждане на инструменти върху Phasis. За програматичен достъп използвайте [анализатора API](https://phasis.inline0.dev/bg/docs/parser).

## bin/test262

`bin/test262` изпълнява [официалния тестов пакет test262](https://github.com/tc39/test262) спрямо Phasis. Полезен е като набор за регресионни тестове при приноси към проекта. Снимката на целия пакет в `COMPAT.md` се генерира от свързания `bin/compat-report`, който CI матрицата стартира ръчно на части.

### Изпълнение на една категория

```bash
./bin/test262 --category built-ins/Array
```

### Изпълнение на целия пакет

```bash
./bin/test262 --jobs 4
```

### Конфигурация

Изпълнителят чете `config/support.php` от основната директория на проекта. Списъкът `test262_skipped_features` е празен: не се пропуска нито една функционалност на test262, включително `tail-call-optimization`. Файлът съдържа и списък с категориите и тестовете, които трябва да се изпълняват изолирано.

Самият пакет за тестове е подмодулът `test262` git; стартирайте `git submodule update --init test262` след клонирането. Без него изпълнителят приключва със съобщението „Не е намерен тестов пакет test262“.

### Други полезни флагове

| Флаг | Предназначение |
|---|---|
| `--failures` | извежда по един ред за всеки неуспешен тест |
| `--limit N` | спира след първите N теста |
| `--jobs N` | изпълнява N теста паралелно |
| `--files-from file` | изпълнява само тестовете, изброени в `file` |
| `--json` | извежда обобщение в машинночетим формат към stdout |
| `--no-progress` | скрива реда за напредъка |

Вижте раздела за [съвместимост](https://phasis.inline0.dev/bg/docs/compatibility) за най-новата снимка.

## bin/wpt

`bin/wpt` изпълнява фикстурите от Web Platform Tests, внесени в `tests/Wpt/fixtures/`. Корпусът обхваща URL, кодиране, atob/btoa, structuredClone, производителност, Headers, Blob/File, AbortController/Signal, EventTarget, FormData, WHATWG Streams, пълния набор от `crypto`/`SubtleCrypto`, `fetch`/`Request`/`Response`, `XMLHttpRequest`/`XMLHttpRequestUpload` и `WebSocket`. Вижте [Уеб API](https://phasis.inline0.dev/bg/docs/compatibility/web-apis) за таблицата с процента на успешно преминатите тестове по области.

### Изпълнение на всички внесени фикстури

```bash
./bin/wpt
```

### Изпълнение на една категория

```bash
./bin/wpt --category headers
./bin/wpt --category streams
./bin/wpt --category blob
```

### Резултат за всеки подтест

```bash
./bin/wpt --category abort --verbose
```

Извежда всеки подтест (PASS / FAIL) във всяка фикстура, заедно със съобщенията от проверките при неуспех.

### Резултат във формат JSON

```bash
./bin/wpt --json
```

Машинночетимо обобщение на успехите и неуспехите за CI конвейери или автоматизиран анализ.

### Бележки

- Фикстурите, които използват Fetch, автоматично стартират включения WPT тестов сървър на `tests/Wpt/fetch-server.php` към `127.0.0.1:8765` и го спират след това.
- Мостът за съвместимост на изпълнителната среда в `tests/Wpt/testharness-shim.js` реализира само набора от WPT API, използван от внесените фикстури (~400 реда спрямо пълния вариант от ~3K реда `testharness.js`).
- Изходните фикстури се намират в `tests/Wpt/upstream/` (рядко клониране, игнорирано от Git, на [web-platform-tests/wpt](https://github.com/web-platform-tests/wpt)). За да внесете още, копирайте файловете `.any.js` от `upstream/<area>/` в `fixtures/<category>/` и изпълнителят ще ги открие автоматично.

## Кодове за изход

`bin/phasis` приключва с един от два кода:

| Код | Значение |
|---|---|
| `0` | успех — скриптът се изпълни докрай (включително след `--ast`) |
| `1` | всичко останало: неуловено изключение JS, синтактична грешка, липсващ файл или невалидни аргументи |

Грешките от скрипта извеждат съобщението си към stderr. Невалидните аргументи и липсващите файлове извеждат реда за употреба към stderr.

## Ограничения на ресурсите

`bin/phasis` работи с настройките на машината по подразбиране и няма флагове за ограничения: лимит от 4,096 кадъра за стека от извиквания на JS, ограничение от 8,192 кадъра за транспилирани затваряния и стандартна `maxLoopIterations` от 100,000, приложима само за код, изпълняван от интерпретатора с обхождане на дървото (вижте [API: setLimit](https://phasis.inline0.dev/bg/docs/api#setlimit)). Няма времеви лимит; използвайте `timeout` около командата, ако скриптът може да не приключи.