README

为什么选择SARB？
要求
安装
使用SARB
进一步阅读

为什么选择SARB？

如果您尝试将高级静态分析工具（例如 Psalm， PHPStan）引入到旧项目中，这些工具可能已经报告了数千个问题。在继续开发之前，修复所有问题，即使是大多数最关键的问题，也是不切实际的。

SARB用于创建这些结果的基础。随着项目的进展，SARB会获取最新的静态分析结果，从基础中移除这些问题，并报告自基准以来提出的问题。SARB通过跟踪提交之间的代码行来实现这一点。目前，SARB仅支持git，但有可能添加对其他SCM的支持。

SARB是用PHP编写的，但它可以用于为任何语言和任何静态分析工具创建基准。

为什么不使用SARB？

SARB不应用于绿地项目。如果您有幸在一个绿地项目中工作，请确保您在开发过程中修复静态分析提出的所有问题。

要求

目前，SARB仅支持使用git的项目。

SARB需要PHP >= 8.0来运行。被分析的项目不需要运行PHP 8.0，甚至不需要是PHP项目。

安装

您可以直接向希望进行分析的项目添加

composer require --dev dave-liddament/sarb

或者您可以在全局范围内安装SARB（例如，如果您想在非PHP项目中使用它）

composer global require dave-liddament/sarb

如果您全局安装，请确保composer的bin目录在您的路径中。

使用SARB

如果您使用的是版本0.x，请参阅旧文档以及如何升级。

1. 确保当前的git提交是基准中要使用的提交

在创建基准时，SARB需要知道基准的git提交SHA。确保您的代码处于您希望它处于基准的状态，并且当前的提交代表了这种状态。

2. 创建基准

运行所选的静态分析器并将结果通过管道传递给SARB

例如，使用Psalm的 JSON输出

vendor/bin/psalm --output-format=json | vendor/bin/sarb create --input-format="psalm-json" psalm.baseline

这会创建一个名为psalm.baseline的基准文件。您希望将其提交到您的存储库中。

3. 更新代码然后使用SARB移除基准结果

继续编码。然后重新运行静态分析器并将结果通过管道传递给SARB

vendor/bin/psalm --output-format=json | vendor/bin/sarb remove psalm.baseline

从全局安装运行SARB

如果您从全局安装运行SARB，您需要指定项目的根目录（.git目录所在的目录）。上面的内容将变为

psalm --output-format=json | sarb create --project-root=/path/to/project/root --input-format="psalm-json" psalm.baseline

支持的工具

要查看支持的工具和格式，请使用

vendor/bin/sarb list-static-analysis-tools

如何为每个支持的工具创建和删除基线

PHP CodeSniffer

vendor/bin/phpcs src --report=json | vendor/bin/sarb create --input-format="phpcodesniffer-json" phpcs.baseline
vendor/bin/phpcs src --report=json | vendor/bin/sarb remove phpcs.baseline

Phan

vendor/bin/phan -m json | vendor/bin/sarb create --input-format="phan-json" phan.baseline
vendor/bin/phan -m json | vendor/bin/sarb remove phan.baseline

请参阅有关相对路径的说明：Relative Paths.

Exakat

php exakat.phar report -p <project> -format sarb | vendor/bin/sarb create --input-format="exakat-sarb" exakat.baseline
php exakat.phar report -p <project> -format sarb | vendor/bin/sarb remove exakat.baseline

PHPMD

vendor/bin/phpmd src json <ruleset> | vendor/bin/sarb create --input-format="phpmd-json" phpmd.baseline
vendor/bin/phpmd src json <ruleset> | vendor/bin/sarb remove phpmd.baseline

Psalm

vendor/bin/psalm --output-format=json | vendor/bin/sarb create --input-format="psalm-json" psalm.baseline
vendor/bin/psalm --output-format=json | vendor/bin/sarb remove psalm.baseline

注意：检查Psalm的内置基线功能。了解它如何与SARB不同。

PHPStan

vendor/bin/phpstan analyse --error-format=json | vendor/bin/sarb create --input-format="phpstan-json" phpstan.baseline
vendor/bin/phpstan analyse --error-format=json | vendor/bin/sarb remove phpstan.baseline

注意：检查PHPStan的内置基线功能。了解它如何与SARB不同。

PHP Magic Number Detector

vendor/bin/phpmnd . | vendor/bin/sarb create --input-format="phpmnd" phpmnd.baseline
vendor/bin/phpmnd . | vendor/bin/sarb remove phpmnd.baseline

请参阅有关相对路径的说明：Relative Paths.

我的工具不受支持...

这没有问题，有三种方法可以将静态分析工具与SARB集成：Custom Input Formats。

输出格式

删除基线后显示问题的格式可以使用--output-format选项指定。可能的值包括：table、text、json或github（用于GitHub Actions）。

忽略警告

某些静态分析工具（例如PHP CodeSniffer）将问题分类为具有严重性或为error或warning。默认情况下，SARB将报告所有这些问题。如果您想忽略警告，可以使用--ignore-warnings选项。

例如：

vendor/bin/phpcs src --report=json | vendor/bin/sarb remove phpcs.baseline --ignore-warnings

SARB与GitHub Actions一起使用

如果您正在使用actions/checkout@v2来检出您的代码，则需要将fetch-depth设置为0。默认情况下，checkout只获取代码的最新状态，而不获取任何历史记录。SARB使用git，它需要完整的git历史记录来跟踪自基线以来的文件更改。要获取完整的历史记录，请使用以下方法：

- uses: actions/checkout@v2
  with:
    fetch-depth: 0

另外，别忘了使用SARB选项--output-format=github。它将为自基线以来添加的任何问题添加注释到PR中。

逐步改进代码库

在一个理想的世界里，SARB不应该被需要。SARB阻止您向代码库添加新的问题。

当运行remove时，它还提供了一个--clean-up选项。使用具有此选项的SARB运行将选择5个仍然在基线中的随机问题。挑战您的团队每天解决基线中的5个问题。在一年工作时间内，这将使基线中的1000个问题消失！很快，您将能够彻底丢弃SARB！

大卫-利达门 / sarb

维护者

详细信息