Сценарии использования¶

Qualimetrix вписывается в различные рабочие процессы разработки. На этой странице описаны наиболее распространённые сценарии и рекомендуемые настройки для каждого из них.

CI/CD Pipeline¶

Самый распространённый сценарий. Qualimetrix запускается при каждом push или pull request и блокирует merge, если стандарты качества не соблюдены.

Рекомендуемая конфигурация:

Используйте only_rules в конфиг-файле, чтобы зафиксировать набор активных правил. Это предотвратит поломку пайплайна при обновлении Qualimetrix, когда добавляются новые правила.
По умолчанию --fail-on=error: предупреждения отображаются, но не приводят к падению сборки. Для более строгого контроля используйте --fail-on=warning.
Используйте baseline для legacy-проектов, чтобы сфокусироваться только на новых нарушениях.
Используйте --format=github для inline-аннотаций в GitHub PR или --format=sarif для вкладки Security на GitHub.

Пример конфигурации (qmx.yaml):

fail_on: error

only_rules:
  - complexity
  - coupling.cbo
  - size

rules:
  complexity.cyclomatic:
    method:
      warning: 10
      error: 20

Пример GitHub Actions workflow:

- name: Run Qualimetrix
  run: vendor/bin/qmx check src/ --format=github --no-progress

Флаг --fail-on=error не нужен в явном виде — это поведение по умолчанию. Добавьте --fail-on=warning, если хотите, чтобы предупреждения также блокировали сборку.

Обновление Qualimetrix в CI¶

При обновлении Qualimetrix до новой версии могут появиться новые правила. Если вы используете only_rules, новые правила не активируются автоматически. Если вы не используете only_rules, просмотрите CHANGELOG на предмет новых правил и либо:

Добавьте их в disabled_rules, если они вам не нужны
Перегенерируйте baseline: vendor/bin/qmx check src/ --generate-baseline=baseline.json

Tip

Комбинация only_rules с baseline даёт максимально стабильный CI. Вы полностью контролируете, какие правила запускаются и какие существующие нарушения игнорируются.

Pre-commit Hook¶

Быстрая обратная связь при локальной разработке. Qualimetrix проверяет только подготовленные к коммиту файлы (staged files).

Установка:

bin/qmx hook:install

Как это работает:

Анализируются только staged PHP-файлы (быстро)
Коммит блокируется при наличии нарушений уровня error
Учитываются настройки qmx.yaml и baseline проекта

Советы:

Если коммит заблокирован, можно исправить проблемы или пропустить хук через git commit --no-verify
Хук автоматически анализирует только staged-файлы
По умолчанию --fail-on=error — предупреждения не блокируют коммит. Добавьте --fail-on=warning для строгого контроля

Note

Хук анализирует именно staged-версию каждого файла. Если вы добавляете частичные изменения (git add -p), проверяется ровно то, что будет закоммичено.

Разработка с AI-ассистентом¶

Разработчик (с AI-ассистентом или без него) пишет код, а затем запускает Qualimetrix для проверки качества перед отправкой на ревью.

Рабочий процесс:

Написать или сгенерировать код
Запустить bin/qmx check src/ для получения списка нарушений
Просмотреть результаты и решить, что исправить, проигнорировать или подавить
Для проблем, требующих исправления, -- исправить вручную или делегировать AI-ассистенту с конкретной инструкцией, например: "уменьши цикломатическую сложность метода X, выделив вспомогательные методы"
Повторно запустить Qualimetrix для проверки исправлений

Советы:

Используйте --format=json, если ваш AI-инструмент лучше работает со структурированными данными
Используйте --report=git:main..HEAD, чтобы видеть нарушения только в изменённых файлах
Текстовый формат уже оптимизирован для терминала и IDE -- специальный "формат для AI" не нужен

Code Review¶

Qualimetrix аннотирует pull request-ы данными о качестве кода, предоставляя ревьюерам объективную информацию наряду с diff-ом.

GitHub -- inline-аннотации (рекомендуется):

- name: Run Qualimetrix
  run: vendor/bin/qmx check src/ --format=github --no-progress

Нарушения отображаются как аннотации warning/error непосредственно на изменённых строках в diff PR. Дополнительная настройка не требуется. По умолчанию --fail-on=error — предупреждения не блокируют сборку.

GitHub -- вкладка Security:

- name: Run Qualimetrix
  run: vendor/bin/qmx check src/ --format=sarif --no-progress > results.sarif

- name: Upload SARIF
  uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: results.sarif

GitLab -- виджет Code Quality:

script:
  - vendor/bin/qmx check src/ --format=gitlab --no-progress > gl-code-quality-report.json
artifacts:
  reports:
    codequality: gl-code-quality-report.json

Ограниченный отчёт:

Чтобы показать нарушения только в изменённых файлах (а не во всём проекте):

vendor/bin/qmx check src/ --report=git:main..HEAD --format=github --no-progress

Tip

Ограниченный отчёт с --report=git:main..HEAD особенно полезен для крупных проектов, где полный отчёт перегрузит ревьюеров уже существующими проблемами.

Сравнение¶

Сценарий	Рекомендуемый формат	Ключевые опции
CI/CD	`github` или `sarif`	`only_rules` в конфиге, `--fail-on=warning` для строгого режима
Pre-commit	`text` (по умолчанию)	Автоматически через `hook:install`
С AI-ассистентом	`text` или `json`	`--report=git:main..HEAD`
Code review	`github`, `sarif` или `gitlab`	`--report=git:main..HEAD`