# 功能矩阵

功能矩阵是一份自动生成的报告，记录每个受支持的标志和行为下，原生工具与 Greph 包装器是否会产生等效输出。对于“Greph 是否支持此功能？”这类问题，它是权威依据。

矩阵通过对确定性的测试工作区执行实际命令探测来重新生成。原始证据位于 [`FEATURE_MATRIX.json`原始数据](https://github.com/inline0/greph/blob/main/FEATURE_MATRIX.json)，渲染后的表格位于 [`FEATURE_MATRIX.md`表格](https://github.com/inline0/greph/blob/main/FEATURE_MATRIX.md)。

## 状态说明

| 状态 | 含义 |
|---|---|
| `Pass` | 探测已运行，且结果符合预期行为 |
| `Fail` | 探测已运行，但结果不符合预期行为 |
| `Unavailable` | 此环境中不存在提供方命令 |

## 章节

矩阵分为六个章节：

1. **rg 兼容性范围**：每项探测都会分别针对上游 `rg` 二进制文件和 `bin/rg` 运行。要将该行标记为受支持，两者都必须 `Pass`。
2. **sg 兼容性范围**：每项探测都会分别针对上游 `sg` 二进制文件和 `bin/sg` 运行。要将该行标记为受支持，两者都必须 `Pass`。
3. **仅限 sg 包装器的范围**：仅针对 `bin/sg` 的探测（包装器提供、而 ast-grep 本身不具备的额外功能）。
4. **原生 greph 范围**：直接测试 `bin/greph` 的探测。没有上游工具可供比较；这些探测会在测试工作区中验证预期行为。
5. **索引 greph 范围**：测试 `bin/greph-index` 的探测（构建、刷新和预热后的文本搜索）。
6. **索引 AST 库范围**：调用 PHP API（`Greph::buildAstIndex()`、`Greph::searchAstIndexed()`、`Greph::buildAstCache()`、`Greph::searchAstCached()`）并检查构建、搜索和刷新的探测。

## 重新生成矩阵

```bash
php bin/feature-matrix
```

在仓库克隆目录中运行，并确保 `rg` 和 `sg` 位于 `PATH` 上；`bin/feature-matrix` 不属于 Composer 包。它会构建测试工作区，针对上游二进制文件（如果已安装）和 Greph 包装器运行每项兼容性探测，记录结构化结果，并写入 `FEATURE_MATRIX.json` 和 `FEATURE_MATRIX.md`。传入 `--stdout` 可输出 Markdown，而不写入任何一个文件。

已提交的文件需手动重新生成；CI 不会重新生成这些文件。CI 运行的 PHPUnit 测试套件会在上游工具标记为不可用时生成矩阵，并检查报告的结构，因此单项探测失败不会导致 CI 失败。发布前请重新生成矩阵并检查差异。

## 矩阵与文档各自的内容

CLI 参考文档以及 [兼容性 / rg](https://greph.inline0.dev/zh/docs/compatibility/rg) 和 [兼容性 / sg](https://greph.inline0.dev/zh/docs/compatibility/sg) 页面描述的是*预期*范围。功能矩阵记录的是*已验证*范围，并在每一行旁列出确切的探测参数。

如果某项功能有文档说明，却未出现在矩阵中，说明文档已过时。如果某项功能出现在矩阵中，却没有文档说明，说明需要补充文档。两者应保持一致。

## 示例行

### rg 兼容性（节选）

| 功能 | rg | bin/rg | 备注 |
|---|---|---|---|
| 固定字符串搜索 | 通过 | 通过 | 探测：`-F needle single.txt` |
| 不区分大小写的固定字符串搜索 | 通过 | 通过 | 探测：`-F -i needle single.txt` |
| 全字匹配搜索 | 通过 | 通过 | 探测：`-F -w needle words.txt` |
| 全局匹配筛选 | 通过 | 通过 | 探测：`--glob *.php function .` |
| 隐藏文件 | 通过 | 通过 | 探测：`--hidden -F secret .` |
| 结构化 JSON 输出 | 通过 | 通过 | 使用 ripgrep JSON 事件语义的探测：`--json -F needle single.txt` |

### sg 兼容性（节选）

| 功能 | sg | bin/sg | 备注 |
|---|---|---|---|
| 使用 `run --pattern` 进行模式搜索 | 通过 | 通过 | 探测：`run --pattern array($$$ITEMS) src/App.php` |
| 通过 `run --rewrite` 进行重写 | 通过 | 通过 | 探测：`run --pattern array($$$ITEMS) --rewrite [$$$ITEMS] src/App.php` |
| 结构化 JSON 流输出 | 通过 | 通过 | 探测：`run --json=stream --pattern dispatch($EVENT) src/App.php` |
| 全部更新重写 | 通过 | 通过 | 探测：`run --pattern array($$$ITEMS) --rewrite [$$$ITEMS] --update-all src/App.php` |

完整表格请见 [`FEATURE_MATRIX.md`完整表格](https://github.com/inline0/greph/blob/main/FEATURE_MATRIX.md)。

## 为何由探测驱动

手动维护的兼容性表格会逐渐过时。包装器的意义在于“放到你以前调用 `rg` 或 `sg` 的位置，它们就能继续工作”；要兑现这一承诺，唯一的办法就是并排运行上游工具和包装器，并比较结果。每次重新生成矩阵时，探测运行器都会执行这些操作。