@nitra/cursor 3.21.1 → 3.23.0

package/rules/python/docs/fix.md

@@ -0,0 +1,163 @@
+# fix.mjs — entry-point правила `python`
+
+## Огляд
+
+Файл `npm/rules/python/fix.mjs` — це **точка входу** для правила з ідентифікатором `python` пакету `@nitra/cursor`. Він виконує дві ролі одночасно:
+
+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`.
+
+Файл є мінімальним shim-ом і свідомо тримається коротким — уся логіка винесена в спільні бібліотеки `scripts/lib/`, щоб усі правила пакету мали однаковий контракт запуску.
+
+## Експорти / API
+
+| Експорт | Тип                      | Призначення                                                                                                                       |
+| ------- | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------- |
+| `run`   | named export, `function` | Library API правила `python`. Викликається CLI-оркестратором або іншим кодом для прогону правила в межах вже існуючого контексту. |
+
+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, unicorn/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`.

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

@@ -0,0 +1,108 @@
+# `applies.mjs` — applies-гейт правила `python`
+
+## Огляд
+
+Модуль `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()`
+
+Тонкий стаб, що друкує єдиний 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 репозиторіях.
+
+### Послідовність викликів (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()` у такому разі не викликається.
+
+### Приклад прямого використання (без CLI)
+
+```js
+import { applies, check } from './applies.mjs'
+
+if (await applies(process.cwd())) {
+  const code = check()
+  process.exitCode = code
+}
+```
+
+### Інваріанти й контракти
+
+- `applies(cwd)` ніколи не модифікує файлову систему.
+- `applies(cwd)` повертає Promise навіть попри синхронну реалізацію — для уніфікованого CLI-контракту з іншими applies-гейтами.
+- `check()` не дублює перевірку `pyproject.toml`: вона вже відбулась у `applies()`. Якщо `check()` викликається без попереднього `applies()`, повідомлення «pyproject.toml знайдено в корені» може ввести в оману, але exit-code від цього не залежить.
+- Файл свідомо не імпортує `tooling.mjs` чи інші concerns — кожен concern завантажується CLI окремо.

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

@@ -0,0 +1,153 @@
+# tooling.mjs — FS-перевірка вимог правила `python.mdc`
+
+## Огляд
+
+Модуль `npm/rules/python/js/tooling.mjs` — це **check-частина** правила `python.mdc` для Python-проєктів, які перейшли на пакет-менеджер [uv](https://github.com/astral-sh/uv). Його єдина відповідальність — перевірити **наявність/відсутність файлів** у корені репозиторію, які не може покрити декларативний шар (`conftest`, `Rego`-policies для `fix`-команди).
+
+Модуль експортує функцію `check(cwd)`, що повертає exit-code (0/1) і друкує діагностику через спільний `check-reporter`. Викликається CLI `@nitra/cursor` після того, як `applies.mjs` вирішив, що правило застосовується до поточного workspace.
+
+Розподіл відповідальностей між шарами правила `python`:
+
+| Шар                                     | Що перевіряє                                                                                                             |
+| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `applies.mjs`                           | Чи це Python-проєкт узагалі (наявність `pyproject.toml` як вхідний гейт).                                                |
+| `tooling.mjs` (цей файл)                | FS-existence: `uv.lock`, `package.json`, `.github/workflows/lint-python.yml`, відсутність `poetry.lock` / `poetry.toml`. |
+| `python/pyproject_toml/` (Rego, `fix`)  | Заборона `[tool.poetry]`, вимога `PEP 621` `[project].name` / `[project].version`.                                       |
+| `python/package_json/` (Rego, `fix`)    | Наявність скрипта `lint-python` у кореневому `package.json`.                                                             |
+| `python/lint_python_yml/` (Rego, `fix`) | Канонічна структура `uses`/`run`-кроків у `.github/workflows/lint-python.yml`.                                           |
+
+Свідомо **не перевіряється** наявність `.venv/`: uv теж створює `.venv/`, тож сам по собі цей каталог не є ознакою Poetry й давав би хибнопозитивні спрацювання.
+
+## Експорти / API
+
+| Символ  | Тип            | Призначення                                                                         |
+| ------- | -------------- | ----------------------------------------------------------------------------------- |
+| `check` | named function | Головна (і єдина) точка входу — FS-перевірка проєкту на відповідність `python.mdc`. |
+
+Default-експорт відсутній. Усі імпорти модуля повинні використовувати іменований імпорт:
+
+```js
+import { check } from './tooling.mjs'
+```
+
+## Функції
+
+### `check(cwd = process.cwd())`
+
+**Сигнатура**
+
+```js
+export function check(cwd = process.cwd()): number
+```
+
+**Параметри**
+
+| Імʼя  | Тип      | Значення за замовч. | Опис                                                                                                                                                                                           |
+| ----- | -------- | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `cwd` | `string` | `process.cwd()`     | Абсолютний шлях до кореня репозиторію, який перевіряється. У звичайному CLI-прогоні передається з runtime; у тестах та standalone-сценаріях — явним аргументом для ізоляції від реального CWD. |
+
+**Повертає**
+
+`number` — exit-code, отриманий від `reporter.getExitCode()`:
+
+- `0` — усі очікувані файли на місці, заборонених артефактів немає.
+- `1` — щонайменше один `fail(...)` був викликаний (відсутня обовʼязкова сутність або присутній заборонений артефакт).
+
+**Side effects**
+
+- Виклик `createCheckReporter()` створює репортер, який пише форматовану діагностику в `stdout` / `stderr` через зареєстровані `pass(message)` та `fail(message)`. Кожен виклик `pass` / `fail` усередині `check()` — потенційний рядок у виведенні CLI.
+- Виконує синхронні `existsSync(...)` для серії шляхів (читання FS — read-only).
+- **Жодних мутацій FS, мережі чи процесу** функція не робить (не пише файли, не виходить через `process.exit`).
+
+**Алгоритм (покроково)**
+
+1. Створює репортер: `const reporter = createCheckReporter()` і деструктурує `{ pass, fail }`.
+2. **Захисний гейт.** Якщо у `cwd` немає `pyproject.toml` — повертає поточний exit-code репортера (на цей момент `0`, оскільки жодних `fail` ще не було). Це дублює гейт `applies.mjs` і потрібне лише для прямого виклику `check()` поза CLI (тести/standalone).
+3. **Перевірка `uv.lock`** (uv-проєкт коммітить lock-файл):
+   - є → `pass('uv.lock є')`,
+   - немає → ``fail('uv.lock не знайдено — згенеруй `uv lock` (python.mdc, без Poetry)')``.
+4. **Заборона Poetry-артефактів.** Для кожного імені з масиву `['poetry.lock', 'poetry.toml']`:
+   - файл існує → `fail('<file> знайдено — прибери Poetry, мігруй на uv (python.mdc)')`,
+   - файла немає → `pass('<file> відсутній')`.
+5. **Наявність кореневого `package.json`** (для запуску `bun run lint-python`):
+   - є → `pass('package.json є (наявність lint-python перевіряє fix → python.package_json)')`,
+   - немає → ``fail('package.json не знайдено в корені — додай для `bun run lint-python` (python.mdc)')``.
+6. **Наявність `.github/workflows/lint-python.yml`** (CI workflow для lint):
+   - є → `pass('<wfPath> є (структуру перевіряє fix → python.lint_python_yml)')`,
+   - немає → `fail('<wfPath> не існує — створи згідно python.mdc')`.
+7. Повертає `reporter.getExitCode()`.
+
+**Інваріанти**
+
+- Послідовність перевірок фіксована й важить для читабельності виводу. Гейт `pyproject.toml` — обовʼязково першим (інакше для не-Python репо посипалися б `fail`-и).
+- Жодна перевірка не «короткозамикає» наступні: навіть якщо `uv.lock` відсутній, далі будуть зроблені перевірки Poetry, `package.json` і workflow — це дозволяє за один прогін побачити повний список проблем.
+
+## Залежності
+
+### Зовнішні (Node.js standard library)
+
+| Імпорт       | Звідки      | Використання                                                                 |
+| ------------ | ----------- | ---------------------------------------------------------------------------- |
+| `existsSync` | `node:fs`   | Синхронна перевірка існування файлу за абсолютним шляхом.                    |
+| `join`       | `node:path` | Кросплатформне склеювання `cwd` із відносним шляхом файла, що перевіряється. |
+
+### Внутрішні (проєкт)
+
+| Імпорт                | Звідки                                    | Використання                                                                                                                                                                        |
+| --------------------- | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `createCheckReporter` | `../../../scripts/lib/check-reporter.mjs` | Фабрика репортера для check-скриптів. Очікувані поля результату: `pass(msg: string)`, `fail(msg: string)`, `getExitCode(): number` (0 поки не було `fail`, 1 після першого `fail`). |
+
+### Зовнішні сутності (контекст правила)
+
+Файл логічно повʼязаний (але **не імпортує** їх) із:
+
+- `npm/rules/python/python.mdc` — текстове формулювання правила.
+- `npm/rules/python/applies.mjs` — гейт, який вирішує, чи запускати `check()`.
+- Rego-полісі `python/pyproject_toml/`, `python/package_json/`, `python/lint_python_yml/` — покривають структурні (а не FS-existence) аспекти, які цей файл свідомо **не** перевіряє.
+
+## Потік виконання / Використання
+
+### Типовий запуск через CLI
+
+```bash
+npx @nitra/cursor check python
+```
+
+CLI послідовно:
+
+1. Резолвить правило `python`.
+2. Викликає `applies(cwd)` — якщо `false`, правило пропускається повністю.
+3. Якщо `true`, викликає `check(cwd)` із цього файла.
+4. Друкує зібрану діагностику й завершується з отриманим exit-code.
+
+### Прямий виклик (тест / standalone)
+
+```js
+import { check } from '@nitra/cursor/rules/python/js/tooling.mjs'
+
+const code = check('/abs/path/to/repo')
+// code === 0 → проєкт відповідає python.mdc
+// code === 1 → у виводі репортера є помилки, треба полагодити
+process.exitCode = code
+```
+
+### Виправлення виявлених проблем
+
+Файл лише **діагностує** — нічого не змінює. Виправлення:
+
+| Проблема (`fail`-message)                       | Що зробити                                                                                                                             |
+| ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| `uv.lock не знайдено`                           | Запустити `uv lock` у корені проєкту й закомітити результат.                                                                           |
+| `poetry.lock знайдено` / `poetry.toml знайдено` | Завершити міграцію з Poetry: видалити файл, перенести залежності в `pyproject.toml` під `[project]` (PEP 621) і згенерувати `uv.lock`. |
+| `package.json не знайдено в корені`             | Створити `package.json` з полем `scripts.lint-python`. Структуру скрипта перевіряє Rego `python.package_json`.                         |
+| `.github/workflows/lint-python.yml не існує`    | Створити workflow за шаблоном з `python.mdc`. Канонічну структуру кроків перевіряє Rego `python.lint_python_yml`.                      |
+
+### Граничні випадки
+
+- **Не-Python репо** (немає `pyproject.toml`) — `check()` повертає `0` без виводу. Безпечно викликати в монорепо корені.
+- **Рівно один `fail`** — exit-code усе одно `1`. Репортер не накопичує «вагу» помилок, лише факт.
+- **Усі `pass`** — exit-code `0`, але всі повідомлення `pass` усе одно потрапляють у вивід (для прозорості та CI-логів).
+
+## Rebuild Test
+
+Документ описує модуль розміром 70 рядків з єдиним експортом `check`, кореневим гейтом по `pyproject.toml`, чотирма блоками перевірок (`uv.lock`, заборона Poetry, `package.json`, workflow `lint-python.yml`), залежністю від `node:fs`, `node:path` та `../../../scripts/lib/check-reporter.mjs`. На основі цього опису можна відтворити функціональний еквівалент: створити фабрику репортера, повернути `getExitCode()` без перевірок при відсутності `pyproject.toml`, інакше — викликати `pass`/`fail` для кожного шляху в наведеному порядку зі вказаними повідомленнями (українська локалізація, посилання на `python.mdc`). Сигнатура `check(cwd = process.cwd()): number`, side effects обмежені виводом репортера й читанням FS.