mirror of
https://github.com/Vateron-Media/XC_VM.git
synced 2026-10-04 12:02:33 +02:00
128 lines
8.1 KiB
Markdown
128 lines
8.1 KiB
Markdown
# Автоматизированный рефакторинг (ректор)
|
||
|
||
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/`, поскольку основное тестовое задание выполняется на основе
|
||
поставщик только для производства, в котором отсутствуют тестовые классы ректора.
|
||
|
||
## КИ
|
||
|
||
Вакансии ректора-консультанта пока нет. Планируется, что это будет отдельная работа только для проверки (промежуточная), которая
|
||
сообщает, но никогда не изменяет репозиторий — смотрите дорожную карту рефакторинга проекта.
|