# 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/ru/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/ru/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 suite not found".

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

| Флаг | Назначение |
|---|---|
| `--failures` | выводить отдельную строку для каждого проваленного теста |
| `--limit N` | остановиться после первых N тестов |
| `--jobs N` | запускать N тестов параллельно |
| `--files-from file` | запускать только тесты, перечисленные в `file` |
| `--json` | выводить машиночитаемую сводку в stdout |
| `--no-progress` | скрыть строку состояния |

Последний снимок результатов см. в разделе [Совместимость](https://phasis.inline0.dev/ru/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 Streams, полный набор `crypto`/`SubtleCrypto`, `fetch`/`Request`/`Response`, `XMLHttpRequest`/`XMLHttpRequestUpload` и `WebSocket`. Таблицу доли пройденных тестов по областям см. в разделе [Веб-API](https://phasis.inline0.dev/ru/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
```

Машиночитаемая сводка PASS/FAIL для конвейеров CI или автоматизированного анализа.

### Примечания

- Тестовые примеры, затрагивающие Fetch, автоматически запускают встроенный тестовый сервер WPT на `tests/Wpt/fetch-server.php` на `127.0.0.1:8765` и останавливают его после завершения.
- Тестовая заглушка в `tests/Wpt/testharness-shim.js` реализует только ту часть интерфейса WPT API, которую используют импортированные тестовые примеры (около 400 строк против примерно 3 тыс. строк в полном `testharness.js`).
- Исходные тестовые примеры находятся в `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` работает с настройками движка по умолчанию и не имеет флагов для ограничения ресурсов: предел глубины стека вызовов 4,096 кадров JS, ограничение в 8,192 кадров для транспилированных замыканий и стандартное значение `maxLoopIterations` — 100,000, применяемое только к коду, который выполняет интерпретатор с обходом дерева (см. [API: setLimit](https://phasis.inline0.dev/ru/docs/api#setlimit)). Ограничения по времени нет; если скрипт может не завершиться, запускайте команду через `timeout`.