@nitra/cursor 3.21.1 → 3.23.0

package/rules/php/docs/fix.md

@@ -0,0 +1,107 @@
+# fix.mjs — правило `php`
+
+## Огляд
+
+Файл `npm/rules/php/fix.mjs` — це точка входу правила `php` у системі `@nitra/cursor`. Він виконує дві ролі одночасно:
+
+1. **Library mode** — експортує функцію `run(ctx)`, яку викликає CLI-оркестратор (`cursor.mjs`) під час масового прогону правил. У цьому режимі правило інтегрується у спільний pipeline і використовує загальний `walkCache` та інший контекст оркестратора.
+2. **Standalone mode** — коли файл запускається напряму через `bun rules/php/fix.mjs`, він діє як самостійний CLI-скрипт, що є повним еквівалентом команди `npx @nitra/cursor fix php` (з підтягуванням конфігурації, whitelist і фінальним summary).
+
+Логіка правила (applies → JS-concerns → policy → mdc-refs) інкапсульована у спільному оркестраторі `runStandardRule`, тож сам файл `fix.mjs` залишається мінімальним «glue»-шаром і не містить специфічної для PHP логіки безпосередньо — конкретні чекери лежать поряд у директорії правила (`checks/`, `applies.mjs`, `policy.mjs` тощо), а їх виявлення робить `runStandardRule` за конвенцією шляху `import.meta.dirname`.
+
+## Експорти / API
+
+| Експорт | Тип                                            | Призначення                                                                                                                                                              |
+| ------- | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `run`   | `function(ctx?: RuleContext): Promise<number>` | Іменований експорт — основний entry-point library-режиму. Запускає стандартний pipeline правила в каталозі поточного модуля. Повертає exit-code (0 — OK, 1 — порушення). |
+
+Файл **не** має `default`-експорту. Side-effect на верхньому рівні модуля: блок `if (isRunAsCli(...))` із викликом `process.exit(...)` — спрацьовує лише при прямому запуску.
+
+## Функції
+
+### `run(ctx)`
+
+```js
+export function run(ctx)
+```
+
+- **Параметри:**
+  - `ctx` _(опціональний)_ — об'єкт типу `RuleContext`, імпортований з `../../scripts/lib/run-standard-rule.mjs`. Передається оркестратором і містить кеш обходу файлової системи (`walkCache`) та інші розшаровані між правилами дані. Якщо не передано — `runStandardRule` створює власний локальний контекст.
+- **Повертає:** `Promise<number>` — exit-code прогону:
+  - `0` — правило пройшло без порушень;
+  - `1` — виявлено порушення (або правило завершилось помилкою, яку оркестратор мапить на ненульовий код).
+- **Side effects:**
+  - Делегує всю реальну роботу `runStandardRule`: читання файлів, виконання чекерів, друк summary до `stdout`/`stderr`.
+  - Сам `run` не має власних побічних ефектів — це тонкий wrapper.
+- **Як визначається корінь правила:** через `import.meta.dirname` — абсолютний шлях до директорії, в якій лежить `fix.mjs`. Це дозволяє `runStandardRule` знайти сусідні файли правила (`applies.mjs`, `policy.mjs`, `checks/*.mjs`, `*.mdc` тощо) без додаткових параметрів.
+
+## Залежності
+
+Файл імпортує дві утиліти з внутрішньої бібліотеки `npm/scripts/lib/`:
+
+| Імпорт            | Звідки                                    | Призначення                                                                                                                                                        |
+| ----------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `isRunAsCli`      | `../../scripts/lib/run-rule-cli.mjs`      | Детектор «чи модуль запущений напряму як CLI». Порівнює `import.meta.url` із `process.argv[1]`. Використовується для гілки standalone.                             |
+| `runRuleCli`      | `../../scripts/lib/run-rule-cli.mjs`      | Повноцінний CLI-runner правила: парсить аргументи, підтягує config, застосовує whitelist, друкує summary. Повертає `Promise<number>` із exit-кодом.                |
+| `runStandardRule` | `../../scripts/lib/run-standard-rule.mjs` | Стандартний pipeline правила: послідовно виконує стадії `applies → JS-concerns → policy → mdc-refs`. Приймає шлях до директорії правила та опційний `RuleContext`. |
+
+Зовнішніх npm-залежностей файл не має — лише внутрішні модулі монорепо.
+
+## Потік виконання / Використання
+
+### Сценарій A — виклик з оркестратора (library mode)
+
+1. CLI `@nitra/cursor fix` (або агрегатор) знаходить правило `php` за його директорією.
+2. Динамічно імпортує `fix.mjs` і викликає `await run(ctx)`, передаючи спільний `RuleContext` (зокрема `walkCache`, щоб уникнути повторного обходу ФС між правилами).
+3. `run` делегує виклик `runStandardRule(import.meta.dirname, ctx)`.
+4. `runStandardRule` повертає exit-code; оркестратор агрегує коди всіх правил.
+
+```js
+import { run } from '@nitra/cursor/rules/php/fix.mjs'
+const code = await run(sharedCtx)
+```
+
+### Сценарій B — прямий запуск файлу (standalone mode)
+
+1. Користувач (або IDE/CI) виконує:
+   ```bash
+   bun npm/rules/php/fix.mjs
+   ```
+2. Top-level `if (isRunAsCli(import.meta.url))` повертає `true` (бо `import.meta.url` збігається з шляхом запущеного скрипта).
+3. Викликається `await runRuleCli(import.meta.dirname)` — повноцінний CLI-режим: підвантажує конфігурацію, застосовує whitelist, друкує підсумок.
+4. `process.exit(...)` завершує процес із отриманим exit-кодом, аби CI/IDE могли коректно інтерпретувати результат.
+
+### Семантика exit-кодів
+
+- `0` — правило застосовне та порушень не виявлено (або правило незастосовне для цього проєкту — `applies` повернув `false`).
+- `1` — є порушення, які треба виправити.
+
+### Коментарі та лінт-винятки
+
+У standalone-гілці явно вимкнено два правила лінтера:
+
+```js
+// eslint-disable-next-line n/no-process-exit, unicorn/no-process-exit -- standalone entry-point має повертати exit-code для CI/IDE
+process.exit(await runRuleCli(import.meta.dirname))
+```
+
+Це свідомий виняток: `process.exit` тут потрібний, щоб CLI/CI отримали ненульовий код у разі порушень — без нього процес міг би завершитись із кодом `0` навіть за наявності знайдених проблем.
+
+## Архітектурний контекст
+
+- **Конвенція файлу `fix.mjs`** — у директорії кожного правила (`npm/rules/<id>/fix.mjs`) лежить однотипний тонкий wrapper із двома ролями (library + standalone). Це гарантує:
+  - єдиний інтерфейс для оркестратора (`run(ctx)`);
+  - можливість запускати окреме правило ізольовано (для дебагу/CI per-rule).
+- **Чому через `import.meta.dirname`** — `runStandardRule` за директорією правила автоматично знаходить усі сусідні артефакти (`applies.mjs`, `policy.mjs`, `checks/*.mjs`, `*.mdc`). Це уникає дублювання id-правила як рядка.
+- **Patch-free wrapper** — у самому `fix.mjs` не повинно з'являтися PHP-специфічної логіки; будь-які зміни поведінки правила робляться у сусідніх файлах правила, а не в цьому entry-point'і.
+
+## Rebuild Test
+
+Файл можна повністю відтворити з опису вище за такими інваріантами:
+
+1. Два імпорти: `{ isRunAsCli, runRuleCli }` з `../../scripts/lib/run-rule-cli.mjs` і `{ runStandardRule }` з `../../scripts/lib/run-standard-rule.mjs`.
+2. Іменований експорт `function run(ctx)` — однорядкове тіло `return runStandardRule(import.meta.dirname, ctx)`.
+3. JSDoc над `run`: опис стадій (applies → JS-concerns → policy → mdc-refs), згадка library mode, тип параметра `ctx` через `import('...').RuleContext`, тип повернення `Promise<number>` із семантикою 0/1.
+4. Блок `if (isRunAsCli(import.meta.url)) { ... }` із викликом `process.exit(await runRuleCli(import.meta.dirname))` і коментарем-поясненням про дві ролі fix.mjs.
+5. Лінт-disable перед `process.exit`: `n/no-process-exit, unicorn/no-process-exit` із обґрунтуванням «standalone entry-point має повертати exit-code для CI/IDE».
+6. Жодних інших top-level операцій, жодного `default`-експорту.

package/rules/php/js/docs/tooling.md

@@ -0,0 +1,152 @@
+# tooling.mjs — перевірка вимог правила `php.mdc`
+
+## Огляд
+
+Модуль `tooling.mjs` реалізує локальну перевірку відповідності PHP-проєкту вимогам внутрішнього правила `php.mdc`. Це частина системи правил Cursor: під кожне правило існує парний `check`-модуль, що повертає exit-code, придатний для запуску в CI або з CLI.
+
+Цей конкретний модуль покриває **лише ту частину вимог, яку неможливо (або недоречно) перевірити через Rego/conftest** — а саме факт існування файлів у файловій системі:
+
+- наявність `composer.json` у корені репозиторію;
+- наявність `package.json` у корені (його структуру, зокрема скрипт `lint-php`, перевіряє вже Rego-політика `npm/policy/php/package_json/`);
+- наявність файлу GitHub Actions workflow `.github/workflows/lint-php.yml` (його вміст, зокрема крок `run: bun run lint-php`, перевіряє Rego-політика `npm/policy/php/lint_php_yml/`).
+
+Тобто `tooling.mjs` — це **FS-existence чек**. Структурний аналіз JSON/YAML делегований на `npx @nitra/cursor check` (Rego). Така декомпозиція явно прописана в JSDoc-заголовку файлу.
+
+Модуль є **ESM** (`.mjs`), не має побічних ефектів на рівні імпорту: уся робота виконується всередині експортованої функції `check()`. Робоча директорія — поточна (`process.cwd()`), оскільки всі шляхи передаються в `existsSync` як відносні.
+
+## Експорти / API
+
+| Експорт   | Тип        | Призначення                                                        |
+| --------- | ---------- | ------------------------------------------------------------------ |
+| `check()` | `function` | Запускає перевірку правила `php.mdc` у поточній робочій директорії |
+
+Інших експортів немає (default-експорту немає). Імпорт здійснюється як іменований:
+
+```js
+import { check } from './tooling.mjs'
+```
+
+## Функції
+
+### `check()`
+
+**Сигнатура:**
+
+```js
+export function check(): number
+```
+
+**Параметри:** немає.
+
+**Повертає:** `number` — exit-code:
+
+- `0` — усі перевірки пройшли (`composer.json`, `package.json` та `.github/workflows/lint-php.yml` існують у поточній директорії);
+- `1` — хоча б одна перевірка провалилася (`fail` був викликаний принаймні один раз).
+
+Конкретне значення exit-code формує об’єкт-репортер через `reporter.getExitCode()` — модуль `tooling.mjs` не визначає логіку підрахунку самостійно, а делегує її в `createCheckReporter()`.
+
+**Алгоритм (по кроках):**
+
+1. Створює локальний репортер: `const reporter = createCheckReporter()`.
+2. Розпаковує методи `pass` і `fail` з репортера: `const { pass, fail } = reporter`.
+3. Перевіряє наявність `composer.json` у CWD:
+   - якщо файл існує → `pass('composer.json існує')`;
+   - інакше → `fail('composer.json не знайдено в корені — додай (php.mdc)')`.
+4. Перевіряє наявність `package.json` у CWD:
+   - якщо файл існує → `pass('package.json є (наявність lint-php перевіряє npx @nitra/cursor fix → php.package_json)')`;
+   - інакше → `fail('package.json не знайдено в корені — додай (php.mdc)')`.
+5. Перевіряє наявність workflow-файлу `.github/workflows/lint-php.yml`:
+   - якщо файл існує → `pass(`${wfPath} є (структуру перевіряє npx @nitra/cursor fix → php.lint_php_yml)`)`;
+   - інакше → `fail(`${wfPath} не існує — створи згідно php.mdc`)`.
+6. Повертає `reporter.getExitCode()`.
+
+**Side effects:**
+
+- **Файлова система:** виключно **читання** (`existsSync`). Жодних записів/створень файлів.
+- **Stdout/stderr:** опосередковано через `pass`/`fail` репортера. Сам модуль не звертається напряму до `console.log` / `process.stdout`. Конкретний канал, формат і обсяг виводу визначає реалізація `createCheckReporter()`.
+- **Process exit:** функція **не викликає** `process.exit()` самостійно — вона лише повертає число. Виклик `process.exit(check())` (або еквівалент) — відповідальність викликаючої сторони.
+- **Глобальний стан:** не змінюється.
+- **CWD-залежність:** усі шляхи відносні, тому результат залежить від поточної робочої директорії на момент виклику.
+
+**Помилки/винятки:** функція не використовує `try/catch`. `existsSync` синхронна та не кидає виняток для відсутніх файлів — повертає `false`. Винятки можуть прилетіти лише з імпортованих залежностей (`createCheckReporter`), якщо ті змінять контракт; цей модуль їх не обробляє.
+
+**Ідемпотентність:** так, виклик не змінює стан системи; повторні виклики дадуть той самий результат за тих самих файлів у CWD.
+
+## Залежності
+
+### Зовнішні (Node.js builtin)
+
+- **`node:fs`** → іменований імпорт `existsSync`. Використовується для синхронної перевірки наявності файлу/директорії за вказаним шляхом. Імпортується саме через префікс `node:` (явна вказівка на builtin-модуль).
+
+### Внутрішні (відносні)
+
+- **`../../../scripts/lib/check-reporter.mjs`** → іменований імпорт `createCheckReporter`. Фабрика репортера для check-модулів. Очікуваний контракт (виведений із використання в цьому файлі):
+  - повертає об’єкт із методами `pass(message: string): void` та `fail(message: string): void`;
+  - має метод `getExitCode(): number`, який повертає `0` за відсутності провалів і `1` (або інше ненульове) за наявності хоча б одного `fail`.
+
+Шлях `../../../scripts/lib/check-reporter.mjs` відраховується від розташування файлу `npm/rules/php/js/tooling.mjs` й веде до `npm/scripts/lib/check-reporter.mjs`.
+
+### Зв’язки з правилами та політиками (контекст екосистеми)
+
+Модуль явно посилається на сусідні артефакти, які виконують споріднену перевірку (вони **не** імпортуються кодом, але є частиною повного контракту правила `php.mdc`):
+
+- `npm/policy/php/package_json/` — Rego-політика, що перевіряє наявність скрипта `lint-php` у `package.json`;
+- `npm/policy/php/lint_php_yml/` — Rego-політика, що перевіряє крок `run: bun run lint-php` у workflow `lint-php.yml`;
+- запускається разом із цим модулем через CLI `npx @nitra/cursor check`.
+
+## Потік виконання / Використання
+
+### Очікуваний контекст запуску
+
+Файл є **check-модулем правила `php.mdc`** і інтегрується в систему `@nitra/cursor`. Виклик відбувається з кореня PHP-проєкту, де очікуються:
+
+- `composer.json` у корені;
+- `package.json` у корені (зі скриптом `lint-php`);
+- `.github/workflows/lint-php.yml` із кроком, який виконує `bun run lint-php`.
+
+### Типовий програмний виклик
+
+```js
+import { check } from './npm/rules/php/js/tooling.mjs'
+
+const code = check()
+process.exit(code)
+```
+
+### Сценарій 1 — усе на місці
+
+CWD містить `composer.json`, `package.json` і `.github/workflows/lint-php.yml`. Репортер отримує три `pass`-повідомлення, жодного `fail`. `check()` повертає `0`.
+
+### Сценарій 2 — немає одного з файлів
+
+Наприклад, відсутній `.github/workflows/lint-php.yml`. Репортер отримує два `pass` і один `fail` із вказівкою «`.github/workflows/lint-php.yml` не існує — створи згідно php.mdc». `check()` повертає `1`.
+
+### Сценарій 3 — порожня директорія
+
+Жоден із трьох файлів не існує. Репортер отримує три `fail` (із підказками щодо `php.mdc`), `check()` повертає `1`. Усі три перевірки виконуються незалежно — функція не виходить на першому ж провалі, тому користувач бачить **повний** список проблем за один прогін.
+
+### Обмеження
+
+- Перевіряється **лише існування** файлів — не їхній уміст. Аналіз структури `package.json` / `lint-php.yml` належить Rego-політикам, які запускаються окремо (`npx @nitra/cursor check`).
+- Не перевіряється, що `composer.json` — валідний JSON або містить обов’язкові поля.
+- Не перевіряється наявність директорії `vendor/`, версії PHP чи що-небудь, пов’язане з виконанням Composer.
+- Усі шляхи відносні до `process.cwd()`. Виклик з іншої директорії дасть інший результат.
+
+### Місце в архітектурі правил
+
+```
+npm/
+├── rules/
+│   └── php/
+│       └── js/
+│           └── tooling.mjs        ← цей файл (FS-existence checks)
+├── policy/
+│   └── php/
+│       ├── package_json/          ← Rego: lint-php у package.json
+│       └── lint_php_yml/          ← Rego: крок bun run lint-php у workflow
+└── scripts/
+    └── lib/
+        └── check-reporter.mjs     ← фабрика репортера (createCheckReporter)
+```
+
+Така структура відображає принцип розділення: JS-модулі правил роблять рівно те, що **не покривається** Rego/conftest (зазвичай — операції з файловою системою, виклики зовнішніх CLI, динамічні перевірки), а декларативні перевірки виносяться в Rego-політики.

package/rules/php/lint/docs/lint.md

@@ -0,0 +1,215 @@
+# lint.mjs — PHP lint runner
+
+## Огляд
+
+Модуль `lint.mjs` реалізує крок `lint-php` згідно з правилом `php.mdc`. Він виконує статичний та безпековий аналіз PHP-проєкту, який лежить у поточному робочому каталозі (`process.cwd()`), послідовно прогоняючи такі інструменти:
+
+1. `composer audit --no-interaction` — обовʼязковий аудит залежностей через Composer.
+2. `vendor/bin/php-cs-fixer fix --dry-run --diff` — перевірка стилю без модифікації файлів.
+3. `vendor/bin/phpcs --standard=Security ...` — перевірка зі стандартом Security для типових директорій коду.
+4. `vendor/bin/phpstan analyse --no-progress` — статичний аналіз.
+5. `vendor/bin/psalm --no-cache` — додатковий статичний аналіз.
+
+Ключові властивості модуля:
+
+- Якщо в корені репозиторію **немає** `composer.json` — скрипт нічого не запускає й завершується успіхом (`pass` + код виходу 0).
+- Якщо `composer.json` є, але `composer` недоступний у `PATH` — це фатальна помилка (`fail`).
+- Інструменти з `vendor/bin/*` запускаються лише за наявності відповідного бінарника; відсутній інструмент **не** є помилкою, лише пропускається з відповідним `pass`-повідомленням.
+- Помилка будь-якого запущеного інструмента (ненульовий exit code) призводить до негайного завершення з кодом помилки — наступні кроки **не** виконуються (fail-fast).
+- Результат акумулюється через `createCheckReporter()`, а підсумковий код виходу дає `reporter.getExitCode()`.
+
+Файл одночасно є модулем (з експортами для повторного використання й тестування) та CLI-точкою входу (через `isRunAsCli(import.meta.url)`).
+
+## Експорти / API
+
+Модуль експортує дві функції:
+
+- `getPhpcsCodePaths(root: string): string[]` — обчислює список директорій для PHPCS.
+- `run(): number` — основна точка входу; повертає код виходу (0 — OK, 1 — є помилки).
+
+Функції `vendorBin`, `runTool` і вкладена `runOptionalVendorTool` є приватними (не експортуються) і використовуються тільки всередині модуля.
+
+Коли модуль виконується безпосередньо як CLI (через `node` чи `bun`), у блоці `if (isRunAsCli(import.meta.url))` викликається `run()`, а результат присвоюється `process.exitCode`.
+
+## Функції
+
+### `getPhpcsCodePaths(root)`
+
+Сигнатура: `getPhpcsCodePaths(root: string): string[]`
+
+Параметри:
+
+- `root` — абсолютний шлях до кореня репозиторію.
+
+Повертає: масив відносних шляхів (рядків) до директорій, які варто передати у `phpcs`.
+
+Алгоритм:
+
+1. Перебирає константу `PHPCS_CODE_DIR_CANDIDATES = ['app', 'src', 'lib', 'public', 'www']`.
+2. Для кожного імені `d` будує абсолютний шлях `join(root, d)` і перевіряє, що шлях існує **і** є директорією (`existsSync` + `statSync(...).isDirectory()`).
+3. Якщо знайдено хоча б одну директорію — повертає масив усіх знайдених імен (як **відносні** імена, не абсолютні шляхи).
+4. Якщо жодної не знайдено — повертає `['.']` (тобто PHPCS буде запущений по всьому кореню).
+
+Side effects: лише читання файлової системи через `existsSync`/`statSync`. Файлів не модифікує.
+
+### `vendorBin(root, name)` (private)
+
+Сигнатура: `vendorBin(root: string, name: string): string | null`
+
+Параметри:
+
+- `root` — корінь репозиторію.
+- `name` — імʼя файла у `vendor/bin` (наприклад, `phpstan`).
+
+Повертає: абсолютний шлях `<root>/vendor/bin/<name>`, якщо файл існує; інакше `null`.
+
+Side effects: `existsSync` (лише читання).
+
+### `runTool(label, abs, args, pass, fail)` (private)
+
+Сигнатура: `runTool(label: string, abs: string, args: string[], pass: (msg: string) => void, fail: (msg: string) => void): boolean`
+
+Параметри:
+
+- `label` — людиночитна назва кроку (наприклад, `"PHPStan"`), використовується в повідомленнях.
+- `abs` — абсолютний шлях до CLI-бінарника.
+- `args` — аргументи командного рядка.
+- `pass` — callback для запису успіху в репортер.
+- `fail` — callback для запису помилки в репортер.
+
+Повертає: `true`, якщо процес завершився з кодом 0; `false` — інакше.
+
+Алгоритм:
+
+1. Запускає `spawnSync(abs, args, { stdio: 'inherit', shell: false })`. `stdio: 'inherit'` означає, що stdout/stderr дитячого процесу пробрасуються користувачу напряму.
+2. Якщо `r.status === 0` — викликає `pass(\`lint-php: ${label} — OK\`)`і повертає`true`.
+3. Інакше визначає код: якщо `r.status` — число, то воно; інакше `1` (захист від `null`, який трапляється, наприклад, при сигналі або провалі запуску).
+4. Викликає `fail(\`lint-php: ${label} — помилка (код ${code}, php.mdc)\`)`і повертає`false`.
+
+Side effects: запускає дочірній процес, успадковує stdio батьківського процесу.
+
+### `run()`
+
+Сигнатура: `run(): number`
+
+Параметри: немає.
+
+Повертає: код виходу — `0` (успіх) або `1` (хоча б одна помилка). Реальний код визначає `reporter.getExitCode()`.
+
+Алгоритм (по кроках):
+
+1. Створює репортер: `const reporter = createCheckReporter()`; деструктуризує `pass` і `fail` з нього.
+2. Бере поточний робочий каталог: `const root = process.cwd()`.
+3. Якщо `composer.json` у корені **відсутній** — викликає `pass('lint-php: немає composer.json у корені — кроки PHP пропущено')` і повертає `reporter.getExitCode()` (фактично 0).
+4. Резолвить бінарник `composer` через `resolveCmd('composer')`. Якщо не знайдено — викликає `fail` з повідомленням про відсутність у `PATH` і виходить.
+5. Запускає `composer audit --no-interaction` через `runTool`. Якщо крок провалився — негайно повертає поточний код виходу (далі нічого не виконується).
+6. Оголошує вкладену функцію `runOptionalVendorTool(binName, label, args): boolean` (див. нижче).
+7. Послідовно викликає `runOptionalVendorTool` для:
+   - `php-cs-fixer` → label `"PHP-CS-Fixer (dry-run)"`, args `['fix', '--dry-run', '--diff']`.
+   - `phpcs` → label `"phpcs (Security)"`, args `['--standard=Security', '--ignore=*/vendor/*,*/node_modules/*,*/.git/*', ...getPhpcsCodePaths(root)]`.
+   - `phpstan` → label `"PHPStan"`, args `['analyse', '--no-progress']`.
+   - `psalm` → label `"Psalm"`, args `['--no-cache']`.
+8. Після кожного кроку, якщо він повернув `false` (тобто `runTool` зафейлився; пропуск через відсутність бінарника `false` **не** дає), функція негайно повертає `reporter.getExitCode()`.
+9. Якщо всі кроки успішні — повертає `reporter.getExitCode()`.
+
+Порядок кроків зафіксований: PHP-CS-Fixer → PHPCS → PHPStan → Psalm. Перший провал зупиняє конвеєр.
+
+Side effects:
+
+- Читає `process.cwd()` і файли в ньому.
+- Резолвить `composer` через `PATH`.
+- Спавнить дочірні процеси з успадкованим stdio.
+- Не модифікує жодних файлів (PHP-CS-Fixer запускається в `--dry-run --diff`).
+- Підсумково повертає число; не викликає `process.exit` самостійно (це робить CLI-обгортка через `process.exitCode`).
+
+### `runOptionalVendorTool(binName, label, args)` (вкладена в `run`)
+
+Сигнатура: `runOptionalVendorTool(binName: string, label: string, args: string[]): boolean`
+
+Параметри:
+
+- `binName` — імʼя файла у `vendor/bin`.
+- `label` — назва кроку для повідомлень.
+- `args` — аргументи CLI.
+
+Повертає: `true`, якщо крок успішний **або** пропущений (бінарника немає); `false`, якщо крок виконано й він зафейлився.
+
+Алгоритм:
+
+1. Резолвить абсолютний шлях через `vendorBin(root, binName)`.
+2. Якщо `null` — викликає `pass(\`lint-php: vendor/bin/${binName} — відсутній, крок пропущено\`)`і повертає`true`.
+3. Інакше делегує `runTool(label, abs, args, pass, fail)` і повертає його результат.
+
+Side effects: ті самі, що в `vendorBin` + `runTool` для виконуваного кроку.
+
+## Залежності
+
+### Стандартна бібліотека Node.js
+
+- `node:child_process` → `spawnSync` — синхронний запуск дочірніх процесів.
+- `node:fs` → `existsSync`, `statSync` — перевірка існування файлів і визначення, чи це директорія.
+- `node:path` → `join`, `resolve` — побудова шляхів (`join` — для відносних, `resolve` — для абсолютних).
+
+### Внутрішні модулі репозиторію (відносні шляхи)
+
+- `../../../scripts/cli-entry.mjs` → `isRunAsCli` — детектор того, що поточний модуль запущений як CLI (порівнює `import.meta.url` зі стартовим файлом).
+- `../../../scripts/lib/check-reporter.mjs` → `createCheckReporter` — фабрика репортера з полями `pass`, `fail`, `getExitCode()`. Усі повідомлення формату `lint-php: <label> — ...` йдуть саме через нього.
+- `../../../scripts/utils/resolve-cmd.mjs` → `resolveCmd` — пошук бінарника в `PATH` (повертає шлях або `null`/`undefined`).
+
+### Зовнішні CLI-залежності (виконувані файли)
+
+- `composer` — має бути у `PATH`, якщо в проєкті є `composer.json`.
+- `vendor/bin/php-cs-fixer`, `vendor/bin/phpcs`, `vendor/bin/phpstan`, `vendor/bin/psalm` — опційні; відсутній бінарник пропускає відповідний крок.
+
+### Правило / контекст
+
+- `php.mdc` — правило з `.cursor/rules/`, на яке посилається модуль (тексти повідомлень містять `php.mdc`).
+
+## Потік виконання / Використання
+
+### Запуск як CLI
+
+```bash
+node npm/rules/php/lint/lint.mjs
+# або через bun
+bun npm/rules/php/lint/lint.mjs
+```
+
+При CLI-запуску виконується блок:
+
+```js
+if (isRunAsCli(import.meta.url)) {
+  process.exitCode = run()
+}
+```
+
+Це означає, що процес завершиться з кодом, що повернула `run()` (0 або 1). Викид `throw` не очікується — усі помилки інструментів повідомляються через `fail`, а не через виключення.
+
+### Імпорт як модуля
+
+```js
+import { run, getPhpcsCodePaths } from './lint.mjs'
+
+const exitCode = run()
+if (exitCode !== 0) {
+  // обробка помилки
+}
+```
+
+`getPhpcsCodePaths` корисна для тестування або для повторного використання логіки вибору директорій.
+
+### Сценарії
+
+1. **Немає `composer.json`** — повертає 0, нічого не запускає, пише в репортер `pass`-повідомлення.
+2. **Є `composer.json`, але немає `composer`** — повертає 1, у репортері є `fail`.
+3. **Є `composer.json` і `composer`, немає жодного `vendor/bin/*`** — запускається лише `composer audit`; якщо він пройде, повертає 0, інші кроки відмічаються як пропущені.
+4. **Усі інструменти встановлені** — послідовний прогін: `composer audit` → `php-cs-fixer` → `phpcs` (за директоріями з `getPhpcsCodePaths`) → `phpstan` → `psalm`. Будь-який ненульовий exit-code дочірнього процесу перериває ланцюг і повертає 1.
+5. **`composer.json` є, директорій `app`/`src`/`lib`/`public`/`www` немає** — PHPCS отримує єдиний шлях `.`.
+
+### Особливості
+
+- `spawnSync` запускається з `shell: false` — параметри передаються як масив, shell-інʼєкції неможливі.
+- `stdio: 'inherit'` — повний вивід інструментів іде в термінал користувача; репортер додає лише підсумкові `pass/fail`-рядки.
+- Fail-fast: модуль не агрегує помилки кількох інструментів; на першій помилці виходить.
+- Усі повідомлення українською, із префіксом `lint-php:` для легкої грепабельності.
+- Функція `run` не приймає аргументів — корінь визначається через `process.cwd()`, що дозволяє запускати її з будь-якого workspace без передавання шляху.