Конфигурация

Qualimetrix работает из коробки с разумными настройками по умолчанию. Файл конфигурации позволяет настроить пороговые значения, отключить правила и исключить пути, чтобы адаптировать инструмент под ваш проект.

---

Файл конфигурации

Создайте файл qmx.yaml в корне проекта. Qualimetrix автоматически ищет этот файл.

Также можно указать файл явно:

vendor/bin/qmx check src/ --config=my-config.yaml

---

Секции конфигурации

Пути для анализа (paths)

Директории для анализа:

paths:
  - src/

Примечание

Если вы передаёте пути через аргументы командной строки (например, vendor/bin/qmx check src/ lib/), они имеют приоритет над конфигурационным файлом.

Исключения (exclude)

Директории, которые полностью пропускаются. Файлы в этих директориях не анализируются вообще:

exclude:
  - vendor/
  - tests/Fixtures/

Включение сгенерированных файлов (include_generated)

По умолчанию файлы с аннотацией @generated в первых 2 КБ автоматически пропускаются при анализе. Чтобы включить их:

include_generated: true

Эквивалент в CLI: --include-generated

Исключение путей из отчёта (exclude_paths)

Паттерны путей для подавления нарушений. В отличие от exclude, эти файлы всё равно анализируются (их метрики собираются), но нарушения не выводятся в отчёт. Поддерживаются префиксы директорий и glob-паттерны:

exclude_paths:
  - src/Entity                # префикс: все файлы в src/Entity/
  - src/Metrics/*Visitor.php  # glob: только файлы визиторов

Исключение неймспейсов (exclude_namespaces)

Подавление нарушений для классов из определённых неймспейсов (сопоставление по префиксу). Как и exclude_paths, файлы всё равно анализируются и метрики собираются, но нарушения не выводятся. Применяется ко всем правилам глобально:

exclude_namespaces:
  - App\Tests
  - App\Generated

Это полезно, когда целые поддеревья неймспейсов не должны генерировать нарушения. Для исключений на уровне отдельного правила используйте exclude_namespaces внутри конфигурации правила (см. ниже).

Также доступна как CLI-опция: --exclude-namespace (объединяется с YAML-конфигурацией).

Правила (rules)

Управление активными правилами и настройка пороговых значений.

Полное отключение правила:

rules:
  code-smell.boolean-argument:
    enabled: false

Переопределение пороговых значений:

Каждое правило определяет уровни серьёзности. Когда метрика превышает порог, фиксируется нарушение соответствующего уровня. Например, правило цикломатической сложности имеет пороги для методов:

rules:
  complexity.cyclomatic:
    method:
      warning: 15
      error: 25

Это означает: выдавать предупреждение (warning), когда цикломатическая сложность метода достигает 15, и ошибку (error), когда достигает 25.

Сокращённая запись threshold:

Если вам нужен простой порог "прошёл/не прошёл" (все нарушения — ошибки), используйте threshold вместо отдельных warning и error:

rules:
  complexity.cyclomatic:
    method:
      threshold: 15   # warning=15 и error=15 → все нарушения становятся ошибками

Это эквивалентно warning: 15 + error: 15. Полезно в CI, где нужен бинарный результат.

Ограничение

Нельзя смешивать threshold с явными ключами warning/error в одном правиле. Используйте либо threshold, либо пару warning/error.

Для правила design.type-coverage доступны специализированные варианты: param_threshold, return_threshold, property_threshold.

Вычисляемые метрики (computed metrics) также поддерживают threshold.

Исключение неймспейсов из правила:

Любое правило может исключить конкретные неймспейсы по префиксу. Нарушения из совпадающих неймспейсов подавляются:

rules:
  complexity.cyclomatic:
    exclude_namespaces:
      - App\Tests
      - App\Legacy
    method:
      warning: 15
      error: 25

  coupling.cbo:
    exclude_namespaces:
      - App\Tests
    exclude_paths:
      - src/Infrastructure/DependencyInjection

Это полезно, когда определённые неймспейсы (например, тесты, сгенерированный код, legacy-модули) не должны вызывать нарушения для конкретного правила, но при этом всё равно анализируются для сбора метрик.

Исключение путей из правила:

Любое правило может исключить конкретные файлы по префиксу пути или glob-паттерну. Нарушения из совпадающих файлов подавляются:

rules:
  coupling.cbo:
    exclude_paths:
      - src/Metrics                # префикс: все файлы в src/Metrics/
      - src/Metrics/*Visitor.php   # glob: только файлы визиторов

Работает совместно с exclude_namespaces -- оба фильтра применяются. В отличие от глобального exclude_paths, эта опция на уровне правила влияет только на конкретное правило, а не на все.

Переопределение порогов для символа через @qmx-threshold:

Помимо общих для проекта порогов в YAML, можно переопределять пороги для отдельных классов или методов с помощью аннотаций @qmx-threshold прямо в исходном коде:

/**
 * @qmx-threshold complexity.cyclomatic method.warning=20 method.error=40
 */
class ComplexStateMachine
{
    // Методы этого класса используют повышенные пороги сложности
}

Полный синтаксис и примеры смотрите в разделе Baseline > @qmx-threshold.

Отключение правил (disabled_rules)

Отключение конкретных правил или целых групп:

disabled_rules:
  - code-smell.boolean-argument
  - duplication

Эквивалент в CLI: --disable-rule=code-smell.boolean-argument --disable-rule=duplication

Только указанные правила (only_rules)

Запустить только указанные правила (все остальные отключаются):

only_rules:
  - complexity.cyclomatic
  - complexity.cognitive

Эквивалент в CLI: --only-rule=complexity.cyclomatic --only-rule=complexity.cognitive

Условие завершения с ошибкой (fail_on)

Управление тем, какие уровни серьёзности приводят к ненулевому коду завершения:

fail_on: error    # Завершение с ошибкой только при error (по умолчанию)
# fail_on: warning  # Завершение с ошибкой и при warning
# fail_on: info     # Завершение с ошибкой при любом нарушении, включая Info
# fail_on: none     # Никогда не завершаться с ошибкой из-за нарушений

Примечание

По умолчанию fail_on установлен в error. Предупреждения и Info-диагностики по-прежнему отображаются в выводе, но не приводят к ненулевому коду завершения. Используйте fail_on: warning, чтобы блокировать сборку и предупреждениями, или fail_on: info, чтобы дополнительно учитывать Info-диагностики (например, architecture.unreachable-layer и architecture.potential-shadow).

Исключение измерений здоровья (exclude_health)

Исключить конкретные измерения здоровья из оценки. Исключённые измерения не отображаются в сводке здоровья и не влияют на общую оценку:

exclude_health:
  - typing
  - maintainability

Эквивалент в CLI: --exclude-health=typing --exclude-health=maintainability

Лимит памяти (memory_limit)

Лимит памяти PHP для анализа. По умолчанию используется значение memory_limit из php.ini.

memory_limit: 1G    # 1 гигабайт
# memory_limit: -1  # Без ограничений

Эквивалент в CLI: --memory-limit=1G

Формат вывода (format)

Формат отчёта по умолчанию:

format: summary   # По умолчанию
# format: json
# format: html

Кэширование (cache)

Управление кэшированием AST для ускорения повторных запусков:

cache:
  enabled: true         # По умолчанию: true
  dir: .qmx-cache       # По умолчанию: .qmx-cache

Эквивалент в CLI: --no-cache для отключения, --cache-dir=DIR для изменения директории.

Параллельная обработка (parallel)

Количество параллельных воркеров для анализа файлов:

parallel:
  workers: 4     # Фиксированное количество воркеров
  # workers: 0   # Отключить параллелизм (однопоточный режим)

По умолчанию Qualimetrix автоматически определяет оптимальное количество воркеров по числу ядер CPU. Эквивалент в CLI: --workers=4

Совет

Используйте workers: 0 для отладки или в окружениях без ext-parallel.

Определение неймспейсов (namespace)

Стратегия определения соответствия неймспейсов и директорий:

namespace:
  strategy: chain          # По умолчанию: chain (сначала psr4, затем tokenizer)
  # strategy: psr4         # Только PSR-4 (требует composer.json)
  # strategy: tokenizer    # Парсинг неймспейса из PHP-токенов
  composer_json: composer.json   # Путь к composer.json для PSR-4

Связанность (coupling)

Настройка префиксов неймспейсов фреймворка для метрики CBO (Coupling Between Objects). Зависимости от неймспейсов фреймворка отслеживаются отдельно как cbo_app и ce_framework:

coupling:
  framework-namespaces:
    - Symfony
    - Doctrine
    - Psr
    - Illuminate

Если framework-namespaces не указаны, cbo_app равен cbo (без эффекта).

Агрегация (aggregation)

Управление группировкой неймспейсов для агрегированных метрик:

aggregation:
  prefixes:
    - App\Domain
    - App\Infrastructure
  auto_depth: 2    # Автоопределение глубины группировки

Архитектура (architecture)

Правила слоёв и allow-list для правила architecture.layer-violation живут под верхнеуровневым ключом architecture:. Полная схема описана в правилах архитектуры; ключи, наиболее релевантные для общей конфигурации:

architecture:
  layers:
    - name: 'domain-{module}'                         # шаблонный слой с переменной захвата
      patterns: ['App\Module\{module}\Domain\**']
    - name: shared-kernel
      patterns: ['App\Shared\**']

  allow:
    'domain-{m}':
      - shared-kernel
      - target: 'domain-{m}'
        relations: [implements, extends]              # whitelist видов зависимостей

  coverage: ignore                                    # ignore | warn | error
  max_expanded_layers: 500                            # кумулятивный лимит на раскрытие шаблонов

Переменные захвата в именах слоёв и паттернах используют синтаксис {name} (один сегмент namespace) или {name:**} (cross-segment). Одно и то же имя переменной в пределах одной записи слоя привязывается к одному значению (co-binding); переменные в разных записях независимы. Полную грамматику см. в секции про шаблонные слои.

max_expanded_layers ограничивает общее количество конкретных слоёв, производимых раскрытием шаблонов по всем шаблонам (по умолчанию 500). Лимит защищает от патологически широких шаблонов, чьи binding tuples взорвали бы число слоёв. Поднимайте предел явно, когда монорепо легитимно содержит больше bounded contexts, чем дефолт; превышение отклоняется на стадии раскрытия с понятной ошибкой.

---

Пресеты

Пресеты — это именованные наборы конфигурации, которые применяют предопределённые настройки: пороговые значения, отключённые правила, поведение при ошибках — одним флагом. Вместо ручной настройки десятков параметров выберите пресет, соответствующий зрелости вашего проекта.

Пресет	Описание
strict	Строгие пороговые значения для новых проектов. Устанавливает fail_on: warning
legacy	Ослабленные пороговые значения для легаси-кодовых баз. Отключает шумные правила
ci	Явный режим CI. Устанавливает fail_on: error

# Использовать один пресет
vendor/bin/qmx check src/ --preset=strict

# Комбинировать несколько пресетов
vendor/bin/qmx check src/ --preset=strict,ci

# Использовать пользовательский файл пресета
vendor/bin/qmx check src/ --preset=./my-preset.yaml

Порядок приоритетов: Пресеты применяются после обнаружения composer.json, но до qmx.yaml. Ваш файл конфигурации всегда переопределяет значения из пресетов.

Несколько пресетов: При комбинировании пресетов они объединяются слева направо — последующие пресеты переопределяют предыдущие, за исключением списковых ключей вроде disabled_rules, которые накапливаются. Например, --preset=legacy,ci даёт ослабленные пороговые значения с поведением CI при ошибках.

Внимание

only_rules не накапливается между пресетами — значение из последнего пресета полностью заменяет предыдущие. Это сделано намеренно: only_rules — это ограничивающий фильтр, и объединение расширяло бы область действия.

Пользовательские пресеты: Любой YAML-файл со структурой qmx.yaml можно использовать как пресет. Передайте путь к файлу вместо имени встроенного пресета.

---

Полный пример

# Или начните с пресета и настройте:
# vendor/bin/qmx check src/ --preset=strict

paths:
  - src/

exclude:
  - vendor/
  - tests/Fixtures/

exclude_paths:
  - src/Entity
  - src/DTO

exclude_namespaces:
  - App\Tests

include_generated: false

format: summary
fail_on: error

cache:
  enabled: true
  dir: .qmx-cache

parallel:
  workers: 4

coupling:
  framework-namespaces:
    - Symfony
    - Doctrine

exclude_health:
  - typing

disabled_rules:
  - code-smell.boolean-argument
  - duplication

rules:
  complexity.cyclomatic:
    exclude_namespaces:
      - App\Tests
    exclude_paths:
      - src/Generated
    method:
      warning: 15
      error: 25

  size.method-count:
    warning: 25
    error: 40

---

Параметры CLI имеют приоритет

Параметры командной строки всегда имеют приоритет над значениями из конфигурационного файла. Например:

# В конфиге указано paths: [src/], но CLI переопределяет
vendor/bin/qmx check lib/

# Добавить дополнительные исключения поверх конфига
vendor/bin/qmx check src/ --exclude-path='src/Generated/*'

Это позволяет экспериментировать без редактирования файла конфигурации.

---

Валидация конфигурации

Qualimetrix валидирует конфигурационный файл и сообщает о типичных ошибках понятными сообщениями.

Неизвестные ключи

Любой нераспознанный ключ — на верхнем уровне или внутри секции — вызывает ошибку с подсказкой:

Invalid configuration in qmx.yaml:
  Unknown key "workes" in "parallel" section. Did you mean "workers"?

Ошибки типов

Если значение имеет неверный тип, вы получите понятное сообщение вместо молчаливого отката на значение по умолчанию:

Invalid value for "cache.enabled": expected boolean, got string

Неизвестные имена правил

Опечатки в именах правил в секции rules: отклоняются:

Unknown rule "complexty.cyclomatic" in qmx.yaml. Did you mean "complexity.cyclomatic"?

Tip

Установите значение ~ (YAML null) или оставьте пустым, чтобы явно использовать значение по умолчанию — это всегда допустимо.

---

Что дальше?

Смотрите справочник параметров CLI для полного списка параметров командной строки.