jbzoo/ci-report-converter

JBZoo / CI-Report-Converter

镜像概述和主要用途

JBZoo/CI-Report-Converter 是一款错误报告格式转换工具，旨在解决各类代码测试、代码规范检查、静态分析工具（如PHPcs、PHPMD、PHPStan等）的输出报告不被主流CI系统（TeamCity、GitHub Actions、GitLab CI等）直接支持的问题。通过将工具生成的原始报告转换为CI系统兼容的格式（如JUnit XML、TeamCity测试报告、GitHub注解等），实现代码质量问题在CI流程中的深度集成与可视化展示，提升开发效率和问题定位速度。

核心功能和特性

支持的输入格式

• checkstyle：适用于Phan、PHP Code Sniffer等工具的XML格式报告
• junit：单元测试常用的XML格式报告
• phpmd-json：PHPMD（PHP Mess Detector）生成的JSON格式详细报告
• phpmnd：PHP Magic Numbers Detector生成的XML格式报告
• pmd-cpd：PMD-CPD（Copy/Paste Detector）生成的XML格式报告
• psalm-json：Psalm静态分析工具生成的JSON格式报告

支持的输出格式

• gitlab-json：GitLab自定义报告格式，用于代码质量集成
• junit：通用的JUnit XML格式，兼容大多数CI系统
• tc-tests：TeamCity测试报告格式，将代码问题展示为失败的单元测试
• tc-inspections：TeamCity代码检查报告格式，集成到IDE风格的检查结果中
• github-cli：GitHub Actions注解格式，直接在PR中展示问题

其他特性

• 支持通过STDIN/STDOUT或文件进行输入输出
• 可自定义根路径，将绝对文件路径转换为相对路径
• 支持TeamCity自定义指标报告（如代码覆盖率、复杂度等）
• 提供GitHub Action，可直接在GitHub workflows中集成

使用场景和适用范围

开发环境集成

• JetBrains IDE（IntelliJ IDEA、PhpStorm等）：将代码规范、静态分析问题转换为单元测试格式，在IDE中直接展示为测试失败，支持一键导航到问题代码。

CI/CD流程集成

• TeamCity：将代码质量问题展示为失败的单元测试或代码检查结果，支持自定义统计指标（如代码行数、复杂度、覆盖率）。
• GitHub Actions：通过注解在PR页面直接展示代码问题，无需查看日志。
• GitLab CI：生成GitLab兼容的JSON报告，集成到合并请求的代码质量分析中。

支持的工具链

适用于各类代码质量工具，包括但不限于：PHP Code Sniffer、PHPMD、PHPStan、Psalm、Phan、PHP Magic Numbers Detector、PHP Copy/Paste Detector等。

使用方法和配置说明

基本使用（Docker命令）

查看帮助

bash
docker run --rm docker.xuanyuan.run/jbzoo/ci-report-converter --help

转换报告（标准输入输出）

bash
# 将PHPcs的checkstyle报告转换为GitHub注解
php ./vendor/bin/phpcs --report=checkstyle ./src | docker run --rm -i jbzoo/ci-report-converter \
  convert \
  --input-format=checkstyle \
  --output-format=github-cli \
  --suite-name=PHPcs

转换报告（文件输入输出）

bash
# 将PHPMD的JSON报告转换为JUnit XML并保存到文件
php ./vendor/bin/phpmd ./src json cleancode > phpmd-report.json
docker run --rm -v $(pwd):/app docker.xuanyuan.run/jbzoo/ci-report-converter \
  convert \
  --input-format=phpmd-json \
  --input-file=/app/phpmd-report.json \
  --output-format=junit \
  --output-file=/app/junit-report.xml \
  --root-path=/app

GitHub Action使用

基本配置示例

yaml
- name: 转换PHPcs报告为GitHub注解
  uses: jbzoo/ci-report-converter@master
  with:
    input-file: build/phpcs-checkstyle.xml  # 输入文件路径
    input-format: checkstyle                # 输入格式
    output-format: github-cli               # 输出格式（默认）
    suite-name: PHP代码规范检查             # 自定义套件名称
    non-zero-code: yes                      # 若发现问题则以非0码退出

完整Workflow示例

yaml
name: 代码质量检查
on: [pull_request]

jobs:
  phpcs:
    runs-on: ubuntu-latest
    steps:
      - name: 检出代码
        uses: actions/checkout@v4

      - name: 安装依赖
        run: composer install --no-progress

      - name: 运行PHPcs
        run: ./vendor/bin/phpcs --report=checkstyle --standard=PSR12 ./src > build/phpcs-checkstyle.xml

      - name: 转换报告为GitHub注解
        uses: jbzoo/ci-report-converter@master
        with:
          input-file: build/phpcs-checkstyle.xml
          input-format: checkstyle
          suite-name: PHP代码规范检查
          non-zero-code: yes

命令行参数说明

convert 命令（报告转换）

teamcity:stats 命令（TeamCity指标报告）

高级示例

TeamCity中展示代码检查结果

bash
# 将PHPStan的checkstyle报告转换为TeamCity检查格式
php ./vendor/bin/phpstan analyse --error-format=checkstyle ./src | docker run --rm -i jbzoo/ci-report-converter \
  convert \
  --input-format=checkstyle \
  --output-format=tc-inspections \
  --suite-name=PHPStan静态分析 \
  --tc-flow-id=phpstan-analysis

生成TeamCity代码统计指标

bash
# 从PHPUnit覆盖率报告提取指标并发送到TeamCity
docker run --rm -v $(pwd):/app docker.xuanyuan.run/jbzoo/ci-report-converter \
  teamcity:stats \
  --input-format=phpunit-clover-xml \
  --input-file=/app/build/phpunit-clover.xml

许可证

本项目基于MIT许可证开源，详情参见https://github.com/JBZoo/CI-Report-Converter/blob/master/LICENSE%E3%80%82