跳转到正文

功能矩阵

以 Markdown 格式查看 在 GitHub 上编辑 文档位置 d105217

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

矩阵通过对确定性的测试工作区执行实际命令探测来重新生成。原始证据位于 FEATURE_MATRIX.json原始数据，渲染后的表格位于 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()）并检查构建、搜索和刷新的探测。

重新生成矩阵

命令行
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 和 兼容性 / 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完整表格。

为何由探测驱动

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