# 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` з `vendor/bin/` зв’язуються `bin/phasis` і `bin/test262`. Звідти працює лише `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/uk/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/uk/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/uk/docs/compatibility).

## bin/wpt

`bin/wpt` запускає фікстури Web Platform Tests, імпортовані до `tests/Wpt/fixtures/`. Корпус охоплює URL, кодування, atob/btoa, structuredClone, performance, Headers, Blob/File, AbortController/Signal, EventTarget, FormData, потоки WHATWG, повну поверхню `crypto`/`SubtleCrypto`, `fetch`/`Request`/`Response`, `XMLHttpRequest`/`XMLHttpRequestUpload` і `WebSocket`. Таблицю відсотка успішно пройдених тестів для кожної області див. у розділі [Веб-API](https://phasis.inline0.dev/uk/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 рядків проти повного `testharness.js` обсягом приблизно 3 тис. рядків).
- Вихідні фікстури розташовані в `tests/Wpt/upstream/` (розріджена копія [web-platform-tests/wpt](https://github.com/web-platform-tests/wpt), яку Git ігнорує). Щоб імпортувати більше, скопіюйте файли `.any.js` з `upstream/<area>/` у `fixtures/<category>/` — засіб запуску підхопить їх автоматично.

## Коди завершення

`bin/phasis` завершується з одним із двох кодів:

| Код | Значення |
|---|---|
| `0` | успіх — скрипт виконався до кінця (також після `--ast`) |
| `1` | будь-який інший випадок: неперехоплений виняток JS, синтаксична помилка, відсутній файл або неприпустимі аргументи |

Помилки скрипту виводяться в stderr. Неприпустимі аргументи й відсутні файли супроводжуються виведенням рядка довідки у stderr.

## Обмеження ресурсів

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