@nitra/cursor 5.3.3 → 5.4.0

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

@@ -1,152 +1,29 @@
-# tooling.mjs — перевірка вимог правила `php.mdc`
+---
+docgen:
+  source: npm/rules/php/js/tooling.mjs
+  crc: a3e6a475
+  score: 95
+---
 
-## Огляд
-
-Модуль `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-залежність:** усі шляхи відносні, тому результат залежить від поточної робочої директорії на момент виклику.
+# tooling.mjs
 
-**Помилки/винятки:** функція не використовує `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`. Усі три перевірки виконуються незалежно — функція не виходить на першому ж провалі, тому користувач бачить **повний** список проблем за один прогін.
+## Поведінка
 
-### Обмеження
+1. Перевірити наявність composer.json
+2. Перевірити наявність package.json
+3. Перевірити наявність .github/workflows/lint-php.yml
 
-- Перевіряється **лише існування** файлів — не їхній уміст. Аналіз структури `package.json` / `lint-php.yml` належить Rego-політикам, які запускаються окремо (`npx @nitra/cursor check`).
-- Не перевіряється, що `composer.json` — валідний JSON або містить обов’язкові поля.
-- Не перевіряється наявність директорії `vendor/`, версії PHP чи що-небудь, пов’язане з виконанням Composer.
-- Усі шляхи відносні до `process.cwd()`. Виклик з іншої директорії дасть інший результат.
+## Публічний API
 
-### Місце в архітектурі правил
+check — Перевіряє відповідність проєкту правилам php.mdc.
 
-```
-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-політики.
+- Read-only: файл не виконує операцій запису у файлову систему.
+- Свідомо пропускає шляхи: `.github`, `.git`.
+- Не звертається до мережі.

package/rules/python/docs/fix.md

@@ -1,172 +1,40 @@
 ---
 docgen:
   source: npm/rules/python/fix.mjs
-  crc: 12fc1644
+  crc: 38cf876b
+  score: 100
 ---
 
-# fix.mjs — entry-point правила `python`
+# fix.mjs
 
 ## Огляд
 
-Файл `npm/rules/python/fix.mjs` — це **точка входу** для правила з ідентифікатором `python` пакету `@nitra/cursor`. Він виконує дві ролі одночасно:
+Виконує застосування JS-занепокоєних на вхідному контексті, застосовує визначену політику, генерує посилання на MDC та повертає результат прогону
 
-1. **Library mode** — експортує функцію `run(ctx)`, яку CLI-оркестратор `npx @nitra/cursor fix` або інші правила можуть викликати програмно через `import { run } from './fix.mjs'`.
-2. **Standalone mode** — коли файл запускається безпосередньо (`bun npm/rules/python/fix.mjs`), він самостійно ініціалізує CLI-шар (завантаження конфіга, whitelist цілей, summary-звіт) і завершує процес із коректним exit-code для CI/IDE.
+## Поведінка
 
-Сам файл нічого не перевіряє і не править — він лише делегує всю роботу стандартному раннеру `runStandardRule`, який за угодою обходить підпапки правила (`applies`, `js`, `policy`, `mdc-refs` тощо) у фіксованому порядку. Конкретні перевірки правила `python` живуть у сусідніх теках (`./js/`, `./lint/`, `./policy/`) і у файлі-описі `./python.mdc`.
+1. Запуск правила.
+    *   Приймає контекст прогону.
+    *   Виконує застосування JS-занепокоєних.
+    *   Застосовує політику.
+    *   Генерує посилання на MDC.
+    *   Повертає результат прогону.
 
-Файл є мінімальним shim-ом і свідомо тримається коротким — уся логіка винесена в спільні бібліотеки `scripts/lib/`, щоб усі правила пакету мали однаковий контракт запуску.
+2. Виконання у режимі CLI.
+    *   Виконується як автономний скрипт.
+    *   Виконує повний еквівалент команди `npx @nitra/cursor fix <id>`.
+    *   Виконує завантаження конфігурації.
+    *   Виконує перевірку дозволів.
+    *   Виконує підбирання списку.
+    *   Виконує підбирання резюме.
 
-## Експорти / API
+## Публічний API
 
-| Експорт | Тип                      | Призначення                                                                                                                       |
-| ------- | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------- |
-| `run`   | named export, `function` | Library API правила `python`. Викликається CLI-оркестратором або іншим кодом для прогону правила в межах вже існуючого контексту. |
+run — запускає правило: applies → JS-concerns → policy → mdc-refs (через runStandardRule).
+Library mode — викликається CLI orchestration через `import + run`.
 
-Default-експорту немає. Експорт `run` має сталу сигнатуру через JSDoc-тип `RuleContext`, імпортований із `../../scripts/lib/run-standard-rule.mjs`.
+## Гарантії поведінки
 
-Окрім експорту, файл містить **side-effect блок** для standalone-режиму — він не експортується, але виконується при безпосередньому запуску модуля.
-
-## Функції
-
-### `run(ctx)`
-
-Public-функція правила, делегатор до `runStandardRule`.
-
-**Сигнатура**
-
-```js
-/**
- *
- */
-export function run(ctx) {
-  return runStandardRule(import.meta.dirname, ctx)
-}
-```
-
-**Параметри**
-
-- `ctx` _(optional)_ — об'єкт типу `RuleContext` (визначений у `../../scripts/lib/run-standard-rule.mjs`). Несе спільний для одного прогону стан: зокрема `walkCache` (закешований обхід дерева файлів, щоб не пере-сканувати робочу копію між правилами) та інші поля, які додає оркестратор. Якщо параметр опущений — `runStandardRule` створить дефолтний контекст самостійно.
-
-**Повертає**
-
-- `Promise<number>` — exit-code прогону:
-  - `0` — порушень не знайдено (правило пройшло),
-  - `1` — знайдено хоча б одне порушення.
-
-Хоча тіло функції `return runStandardRule(...)` синхронне, сам `runStandardRule` повертає `Promise`, тому викликач має `await`-ити результат.
-
-**Side effects**
-
-Безпосередньо у `run` побічних ефектів немає — усі вони виконуються всередині `runStandardRule`:
-
-- читання файлів проекту (через `walkCache`/файлову систему),
-- запуск підправил (applies/JS-concerns/policy/mdc-refs),
-- запис у `stdout`/`stderr` діагностики (summary вмикається лише в standalone-режимі через `runRuleCli`).
-
-Сам `run` **не викликає** `process.exit` — це обов'язок зовнішнього оркестратора. Це принципово, бо `run` має бути безпечним для виклику з іншого правила або тесту.
-
-### Standalone-блок (anonymous side-effect)
-
-```js
-if (isRunAsCli(import.meta.url)) {
-  // eslint-disable-next-line n/no-process-exit
-  process.exit(await runRuleCli(import.meta.dirname))
-}
-```
-
-Не функція, а top-level async-блок (використовує `await` на рівні модуля, що валідно для ES-модулів).
-
-**Як працює**
-
-1. `isRunAsCli(import.meta.url)` — повертає `true`, тільки якщо модуль є entry-point процесу (`bun rules/python/fix.mjs`, а не імпорт). При імпорті з іншого модуля гілка не виконується.
-2. `runRuleCli(import.meta.dirname)` — повний CLI-цикл одного правила: завантажує конфіг проекту, формує whitelist цілей, прогоняє `run` (через `runStandardRule`), друкує summary.
-3. `process.exit(<exit-code>)` — терміново завершує процес кодом, який повернув `runRuleCli`. Дві ESLint-директиви (`n/no-process-exit`, `unicorn/no-process-exit`) явно дозволяють виклик `process.exit` саме тут, бо standalone entry-point повинен повернути код процесу для CI/IDE-інтеграції.
-
-**Side effects**
-
-- Завершує Node/Bun-процес (`process.exit`).
-- Усе, що робить `runRuleCli` (читання конфіга, файлові обходи, лог summary).
-
-## Залежності
-
-Усі залежності — внутрішні модулі того ж пакету (`@nitra/cursor`):
-
-| Модуль                                    | Імпортовані символи        | Роль                                                                                                                                                                                      |
-| ----------------------------------------- | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `../../scripts/lib/run-rule-cli.mjs`      | `isRunAsCli`, `runRuleCli` | Детектор standalone-запуску й повний CLI-цикл одного правила (config + whitelist + summary).                                                                                              |
-| `../../scripts/lib/run-standard-rule.mjs` | `runStandardRule`          | Стандартний раннер правила: обходить підпапки `applies → js → policy → mdc-refs` у фіксованому порядку й агрегує exit-code. Також експортує тип `RuleContext` (використовується в JSDoc). |
-
-Зовнішніх npm-залежностей у файлі немає. Файл покладається лише на ES-модульні runtime-API:
-
-- `import.meta.dirname` — абсолютний шлях до теки модуля (`.../npm/rules/python/`). Передається як «корінь правила» в обидва раннери, щоб вони знали, де шукати підпапки.
-- `import.meta.url` — URL модуля (`file://...`), потрібен `isRunAsCli`, щоб порівняти з `process.argv[1]`.
-- `process.exit` — глобальний Node/Bun API.
-- Top-level `await` — стандарт ESM.
-
-## Потік виконання / Використання
-
-### Сценарій 1. Виклик з оркестратора (library mode)
-
-Коли користувач запускає `npx @nitra/cursor fix python` (або просто `npx @nitra/cursor fix`, де `python` потрапляє у whitelist), CLI-оркестратор пакету:
-
-1. Імпортує `run` із цього файлу: `const { run } = await import('.../npm/rules/python/fix.mjs')`.
-2. Створює спільний `RuleContext` (зокрема `walkCache`).
-3. Викликає `await run(ctx)` і збирає exit-code.
-
-У цьому сценарії `if (isRunAsCli(...))` повертає `false`, бо модуль імпортовано — standalone-блок не виконується, `process.exit` не викликається.
-
-### Сценарій 2. Прямий запуск (standalone mode)
-
-```bash
-bun npm/rules/python/fix.mjs
-# або еквівалент:
-npx @nitra/cursor fix python
-```
-
-1. Модуль виконується як entry-point — `isRunAsCli(import.meta.url)` → `true`.
-2. Викликається `runRuleCli(import.meta.dirname)`:
-   - завантажує конфіг проекту,
-   - формує whitelist цілей,
-   - усередині сам викликає `run(ctx)` (через `runStandardRule`),
-   - друкує summary-звіт.
-3. `process.exit` із отриманим exit-code (`0` або `1`) — придатно для CI (`bun npm/rules/python/fix.mjs && echo OK`).
-
-### Внутрішній порядок підправил
-
-Згідно з JSDoc до `run`, `runStandardRule` запускає послідовність:
-
-1. **applies** — фільтр «чи правило взагалі застосовне до проекту» (читає метадані `meta.json` / контекст).
-2. **JS-concerns** — JS-перевірки (у цьому правилі живуть у `./js/`).
-3. **policy** — політики (у цьому правилі — `./policy/`).
-4. **mdc-refs** — перевірка посилань усередині `python.mdc`.
-
-Будь-яке порушення на будь-якому етапі підвищує exit-code до `1`, але всі етапи прогоняються — щоб користувач бачив повний список порушень за один прохід, а не виправляв їх по одному.
-
-### Чому дві ролі в одному файлі
-
-Це угода всього пакету `@nitra/cursor`: кожне правило має один `fix.mjs`, який:
-
-- легко імпортувати з іншого правила/коду (named export `run`),
-- легко запустити вручну для діагностики конкретного правила (`bun rules/<id>/fix.mjs`),
-- однаково поводиться під CLI-оркестратором і в standalone.
-
-Сусідні правила (наприклад, `npm/rules/n-bun/fix.mjs`, `npm/rules/n-adr/fix.mjs`) мають той самий шаблон — це дає змогу мати один універсальний loader і не дублювати CLI-код у кожному правилі.
-
-## Rebuild Test
-
-Контрольний перелік, за яким можна відтворити файл «з нуля», маючи лише цю документацію:
-
-1. Файл — ES-модуль (`.mjs`), без default-експорту, із одним named export `run`.
-2. Імпорти (у такому порядку):
-   - `isRunAsCli` та `runRuleCli` з `../../scripts/lib/run-rule-cli.mjs`,
-   - `runStandardRule` з `../../scripts/lib/run-standard-rule.mjs`.
-3. Функція `run(ctx)`:
-   - `export function run(ctx)`,
-   - тіло: `return runStandardRule(import.meta.dirname, ctx)`,
-   - JSDoc із описом «applies → JS-concerns → policy → mdc-refs», згадкою про library mode, `@param {RuleContext} [ctx]` і `@returns {Promise<number>}` (0 — OK, 1 — порушення).
-4. Standalone-блок:
-   - `if (isRunAsCli(import.meta.url)) { ... }`,
-   - усередині: `process.exit(await runRuleCli(import.meta.dirname))`,
-   - над `process.exit` — коментар-пояснення дволикої ролі fix.mjs та `eslint-disable-next-line n/no-process-exit, unicorn/no-process-exit` із причиною.
-5. Файл не містить жодної додаткової логіки — усі перевірки правила живуть у сусідніх теках (`./js/`, `./lint/`, `./policy/`) та `./python.mdc`.
+- Read-only: файл не виконує операцій запису у файлову систему.
+- Кешує результати в межах одного прогону.
+- Не звертається до мережі.

package/rules/python/js/docs/applies.md

@@ -1,108 +1,30 @@
-# `applies.mjs` — applies-гейт правила `python`
+---
+docgen:
+  source: npm/rules/python/js/applies.mjs
+  crc: ed79bd71
+  score: 100
+---
 
-## Огляд
-
-Модуль `applies.mjs` реалізує **applies-гейт** для правила `python` (`python.mdc`) у системі правил `n-cursor`. Його єдина роль — відповісти на питання: «чи варто застосовувати правило `python.mdc` до поточного репозиторію?».
-
-Критерій застосовності — наявність файлу `pyproject.toml` у корені репозиторію. Якщо файл відсутній, CLI `n-cursor` пропускає всі concerns цього правила (як JS-перевірки, так і policy-перевірки Rego). Це усуває хибне спрацювання rego-правила `python/package_json`, яке вимагало б наявність npm-скрипта `scripts.lint-python` навіть у репозиторіях, що не пов'язані з Python.
-
-Сам JS-файл не виконує жодних інших FS-перевірок: усі подальші перевірки (`uv.lock`, `package.json`, `lint-python.yml`, заборона Poetry тощо) розміщені окремо у `tooling.mjs`. Окрім гейта `applies()`, файл містить тонкий стаб `check()`, який друкує context-pass через стандартний reporter.
-
-## Експорти / API
-
-Модуль експортує дві named-функції (ESM):
-
-| Експорт   | Тип / сигнатура                      | Призначення                                                           |
-| --------- | ------------------------------------ | --------------------------------------------------------------------- |
-| `applies` | `(cwd?: string) => Promise<boolean>` | Гейт застосовності правила: `true`, якщо в корені є `pyproject.toml`. |
-| `check`   | `() => number`                       | Друкує context-pass через `check-reporter`, повертає exit-code (`0`). |
-
-Default-export відсутній.
-
-## Функції
-
-### `applies(cwd = process.cwd())`
-
-Гейт застосовності правила `python.mdc` для конкретного репозиторію.
-
-- **Сигнатура:** `export function applies(cwd?: string): Promise<boolean>`
-- **Параметри:**
-  - `cwd` _(string, опційний)_ — абсолютний (або відносний) шлях до кореня репозиторію, у якому виконується перевірка. За замовчуванням — результат `process.cwd()`. У звичайному прогоні CLI це робочий каталог, з якого запущено команду.
-- **Повертає:** `Promise<boolean>`
-  - `true` — у `cwd` існує файл `pyproject.toml`, правило `python.mdc` слід застосовувати (CLI запустить решту concerns).
-  - `false` — `pyproject.toml` відсутній, правило треба повністю пропустити.
-- **Алгоритм:**
-  1. Будує абсолютний шлях `join(cwd, 'pyproject.toml')`.
-  2. Викликає синхронну `existsSync()` з `node:fs`.
-  3. Загортає синхронний boolean у `Promise.resolve(...)`, щоб відповідати очікуваному CLI-контракту `Promise<boolean>`.
-- **Side effects:** немає — лише читання метаданих файлової системи (`stat`-like виклик). Файл не відкривається й не читається; запис не виконується; глобальний стан не змінюється.
-- **Помилки:** функція не очікує винятків; `existsSync` сам по собі не кидає для відсутніх шляхів — повертає `false`. Промісована обгортка зберігає таку ж поведінку.
-
-### `check()`
+# applies.mjs
 
-Тонкий стаб, що друкує єдиний context-pass і завершується успіхом. Фактичні порушення (на кшталт відсутності `lint-python`-job у CI, заборони Poetry тощо) перевіряють інші concerns правила, тож тут жодних реальних перевірок немає.
-
-- **Сигнатура:** `export function check(): number`
-- **Параметри:** немає.
-- **Повертає:** `number` — exit-code, отриманий з `reporter.getExitCode()`. Оскільки викликається лише `reporter.pass(...)`, код завжди `0` (немає фейлів).
-- **Алгоритм:**
-  1. Створює інстанс reporter-а через `createCheckReporter()`.
-  2. Викликає `reporter.pass('pyproject.toml знайдено в корені — застосовую python.mdc')`, що друкує позитивний рядок у стандартному форматі n-cursor reporter-а.
-  3. Повертає `reporter.getExitCode()`.
-- **Side effects:** пише в `stdout` (через reporter). Не виконує FS-операцій, не змінює стану процесу, не кидає винятків.
-- **Передумова:** функцію має сенс викликати лише після того, як `applies()` повернула `true` (інакше повідомлення про «знайдено» було б оманливим). CLI `n-cursor` забезпечує цей контракт.
-
-## Залежності
-
-### Зовнішні (стандартна бібліотека Node.js)
-
-- `node:fs`
-  - `existsSync(path)` — синхронна перевірка існування шляху. Використовується для виявлення `pyproject.toml`.
-- `node:path`
-  - `join(...segments)` — нормалізована побудова шляху, незалежна від OS-роздільника.
-
-### Внутрішні (репозиторій)
-
-- `../../../scripts/lib/check-reporter.mjs`
-  - `createCheckReporter()` — фабрика стандартного reporter-а для `check.mjs`-скриптів правил. Очікувані методи: `pass(message)` (друк позитивного рядка) та `getExitCode()` (повертає накопичений exit-код, `0` для успіху).
-  - Відносний шлях вказує на спільну бібліотеку скриптів правил у тому ж `npm/`-пакеті (`npm/scripts/lib/check-reporter.mjs` відносно файлу `npm/rules/python/js/applies.mjs`).
-
-Інших залежностей (зокрема — TOML-парсера, інших правил, `tooling.mjs`) у цьому файлі немає.
-
-## Потік виконання / Використання
-
-### Місце в архітектурі правил
-
-У системі правил `n-cursor` кожне правило (наприклад, `python.mdc`) описується трьома шарами:
-
-1. **`*.mdc`** — людинозрозумілий опис правила, без алгоритму перевірки.
-2. **`js/applies.mjs`** — гейт застосовності правила до конкретного репозиторію (поточний файл).
-3. **`js/<concern>.mjs`** і Rego-policy — фактичні перевірки (`tooling.mjs`, `package_json.rego` тощо).
+## Огляд
 
-CLI `n-cursor` під час прогону правил викликає `applies()` для кожного правила перед тим, як запускати решту concerns. Якщо `applies()` повертає `false`, **усі** перевірки правила (JS і policy) пропускаються. Це й розв'язує проблему хибних спрацювань rego-правила `python/package_json` у не-Python репозиторіях.
+Файл перевіряє наявність файлу pyproject.toml у корені репозиторію.
 
-### Послідовність викликів (happy path)
+## Поведінка
 
-1. Користувач запускає `n-cursor check` (або еквівалент) у корені репо.
-2. CLI обходить набір правил, серед яких `python`.
-3. CLI імпортує `npm/rules/python/js/applies.mjs` і викликає `applies(process.cwd())`.
-4. Якщо `pyproject.toml` присутній — CLI продовжує: запускає `check()` (друк context-pass) та інші concerns правила (`tooling.mjs`, Rego-policy).
-5. Якщо `pyproject.toml` відсутній — CLI повністю пропускає `python` для цього прогону. `check()` у такому разі не викликається.
+applies
+Перевіряє наявність pyproject.toml в корені репозиторію
 
-### Приклад прямого використання (без CLI)
+check
+Друкує повідомлення про знахідку pyproject.toml для застосування python.mdc
 
-```js
-import { applies, check } from './applies.mjs'
+## Публічний API
 
-if (await applies(process.cwd())) {
-  const code = check()
-  process.exitCode = code
-}
-```
+applies — формує намір файлу
+check — виводить короткий контекст-прохід
 
-### Інваріанти й контракти
+## Гарантії поведінки
 
-- `applies(cwd)` ніколи не модифікує файлову систему.
-- `applies(cwd)` повертає Promise навіть попри синхронну реалізацію — для уніфікованого CLI-контракту з іншими applies-гейтами.
-- `check()` не дублює перевірку `pyproject.toml`: вона вже відбулась у `applies()`. Якщо `check()` викликається без попереднього `applies()`, повідомлення «pyproject.toml знайдено в корені» може ввести в оману, але exit-code від цього не залежить.
-- Файл свідомо не імпортує `tooling.mjs` чи інші concerns — кожен concern завантажується CLI окремо.
+- Read-only: файл не виконує операцій запису у файлову систему.
+- Не звертається до мережі.