XC_VM/docs/ru/guides/refactoring.md

# Автоматизированный рефакторинг (ректор)

XC_VM использует [Rector](https://getrector.com/) для модернизации устаревших PHP механических и
безопасно. Ректор переписывает код на **АСТ** (не текст), поэтому каждое преобразование выполняется
детерминированный и воспроизводимый. Он скорее дополняет существующие инструменты, чем заменяет
их:

|Инструмент|Роль|
| --- | --- |
| **Rector** |*Изменения* код — механическая модернизация и упрощение|
|ПХПСтан|Тип отчетов/логические проблемы (`make phpstan`)|
|phpcs / Слевомат|Сообщает и исправляет стиль кодирования (`make cs` / `make cs-fix`)|
|Модуль PHP|Проверяет поведение (`tests/phpunit.phar`)|

**Золотое правило: обнаружить → показать разницу → проверить → только после этого применить.** Никогда не наносите средство массово.
к производственному коду без предварительного просмотра пробного запуска.

## Устанавливать

Rector является зависимостью `require-dev` от `src/composer.json` (как PHPStan и phpcs). Это
**никогда** отгружено: зафиксированное `src/vendor/` доступно только для производства.

```bash
make dev-tools     # composer install (incl. require-dev) — adds Rector to src/vendor
```

Перед приготовлением всегда подрезайте их:

```bash
make dev-clean     # composer install --no-dev — restores a production-only vendor
```

Шлюз `check-vendor-prod-only` завершается сбоем, если Rector когда-либо попадает к зарегистрированному поставщику, так что
`make dev-clean` является обязательным перед любой фиксацией, которая затрагивает зависимости.

## Бежать

```bash
make rector        # dry-run: prints the diff, writes nothing (non-zero exit if changes pend)
make rector-fix    # applies the changes in place
```

Эквивалентные Composer скрипты (запускаемые из `src/`):

```bash
composer refactor:dry
composer refactor
```

После изменений **обратившийся** всегда запускайте полный конвейер проверки и просматривайте разницу:

```bash
make cs-fix        # reconcile style (tabs / K&R) with the rewritten files
make phpstan
php tests/phpunit.phar -c tests/phpunit.xml.dist
```

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

Единственная конфигурация - это [`build/rector.php`](https://github.com/Vateron-Media/XC_VM/blob/main/build/rector.php)
(рядом с `build/phpstan.dist.neon` и `build/phpcs.xml.dist`). Пути привязываются с помощью
`__DIR__`, поэтому он ведет себя одинаково как из корневого хранилища, так и из `src/`.

### Масштаб

В области видимости находятся только деревья на основе классов PSR-4:

```text
src/Core  src/Domain  src/Cli  src/Infrastructure
```

Все остальное равно **исключенный** и должно оставаться исключенным:

- `src/Public/**`, `src/Ministra/**` — view templates use short tags (`<?`/`<?=`); procedural
точки входа зависят от позиционного импорта `use`, применяемого шлюзом `check-procedural-use`.
- `src/Infrastructure/Tmdb/lib/**` — устаревшая глобальная библиотека `\TMDB` (не PSR-4).
- `src/Modules/**` — установленный во время выполнения (может быть закодирован в ionCube).
- `src/vendor/**`, `src/migrations/**`, `src/bin/**`, runtime dirs (`tmp`, `backups`, …).
- **Streaming hot-path** (`src/Streaming/**`, `src/Public/stream/**`, the streaming bootstraps,
`Fanout*Command`) — более высокий риск, переработанный позже на своей собственной осторожной фазе.

### Включенные правила

Конфигурация позволяет использовать подготовленные наборы `deadCode` и `codeQuality` с сохранением поведения
упрощение и удаление ненужного кода. "Пустой-`if` с `else`" -антипаттерн, который, в свою очередь, может быть
(pervasive in the legacy code) is collapsed by the built-in `RemoveDeadIfForeachForRector`:

```php
if (!$user) {
} else {
    doThing();
}
// becomes:
if ($user) {
    doThing();
}
```

Это оставляет непустые тела, пустые тела с комментариями и цепочки `elseif` нетронутыми. Нет пользовательского
для этого необходимо правило — встроенная программа уже делает это, и делает это чисто.

### Намеренно отключенные (изменяющие поведение) правила

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

- `SafeDeclareStrictTypesRector` — добавляет `declare(strict_types=1)`, изменяя приведение к int/string.
- `UseIdenticalOverEqualWithSameTypeRector` — `==` → `===`, который зависит от типа файла.

Правила добавления импорта также отключены (по умолчанию), чтобы защитить ворота `check-procedural-use`.

## Добавление правила для конкретного проекта

Предпочитайте встроенное правило, если таковое существует. Если вам действительно нужно преобразование, специфичное для XC_VM:

1. Добавьте класс в соответствии с `tools/rector/src/` (правило ректора распространяется и на `Rector\Rector\AbstractRector`).
2. Подключите его пространство имен с помощью записи `autoload-dev` PSR-4 в `src/composer.json`, затем
`composer dump-autoload` из `src/`.
3. Запишите его в `build/rector.php` с помощью `->withRules([...])`.
4. Добавьте обязательные тесты (ректорские `AbstractRectorTestCase`, `before/after`, разделенные на `-----`) в
**разделять** PHPUnit suite, а не `tests/Unit/`, поскольку основное тестовое задание выполняется на основе
поставщик только для производства, в котором отсутствуют тестовые классы ректора.

## КИ

Вакансии ректора-консультанта пока нет. Планируется, что это будет отдельная работа только для проверки (промежуточная), которая
сообщает, но никогда не изменяет репозиторий — смотрите дорожную карту рефакторинга проекта.