# CLI

Phasis 在 `bin/` 中提供三个主要可执行文件：

- **`bin/phasis`** — 运行 JavaScript 文件、求值命令行传入的源代码、转储 AST。
- **`bin/test262`** — 对 Phasis 运行官方 ECMAScript 一致性测试套件。
- **`bin/wpt`** — 对 Phasis 运行 Web Platform Tests fixture（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、没有标准输入，也没有模块标志。

### 运行文件

```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/zh/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/zh/docs/parser)。

## bin/test262

`bin/test262` 会对 Phasis 运行 [官方 test262 测试套件](https://github.com/tc39/test262)。为项目贡献更改时，它可用作回归测试框架。`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/zh/docs/compatibility)。

## bin/wpt

`bin/wpt` 会运行导入到 `tests/Wpt/fixtures/` 中的 Web Platform Tests 测试样例。测试集涵盖 URL、编码、atob/btoa、structuredClone、performance、Headers、Blob/File、AbortController/Signal、EventTarget、FormData、WHATWG Streams、完整的 `crypto`/`SubtleCrypto` 接口、`fetch`/`Request`/`Response`、`XMLHttpRequest`/`XMLHttpRequestUpload` 以及 `WebSocket`。各领域的通过率表请参阅[Web API](https://phasis.inline0.dev/zh/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 的测试样例会在 `127.0.0.1:8765` 上自动启动捆绑的 WPT 测试服务器 `tests/Wpt/fetch-server.php`，并在完成后关闭。
- 位于 `tests/Wpt/testharness-shim.js` 的测试框架垫片仅实现导入测试样例所用的 WPT API 接口（约 400 行，而完整的 `testharness.js` 约有 3K 行）。
- 源测试样例位于 `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/zh/docs/api#setlimit)）。没有时间限制；如果脚本可能无法终止，请用 `timeout` 包裹命令。