@nitra/cursor 12.6.1 → 12.8.0

package/rules/nginx-default-tpl/main.mjs

@@ -0,0 +1,20 @@
+import { isRunAsCli, runRuleCli } from '../../scripts/lib/run-rule-cli.mjs'
+import { runStandardRule } from '../../scripts/lib/run-standard-rule.mjs'
+
+/**
+ * Єдиний entrypoint правила (ADR 2026-06-21). `run()` — check-поверхня: applies →
+ * JS-concerns → policy → mdc-refs (через runStandardRule). Lint-поверхні правило не має
+ * (`meta.json` без `lint`), тож експорту `lint` тут немає.
+ * Library mode: викликається CLI orchestration через `import + run(ctx)`.
+ * @param {import('../../scripts/lib/run-standard-rule.mjs').RuleContext} [ctx] контекст прогону (walkCache тощо)
+ * @returns {Promise<number>} 0 — OK, 1 — порушення
+ */
+export function run(ctx) {
+  return runStandardRule(import.meta.dirname, ctx)
+}
+
+if (isRunAsCli(import.meta.url)) {
+  // Standalone: bun rules/<id>/main.mjs — повний еквівалент `npx @nitra/cursor check <id>`
+  // (config-loading + whitelist + summary): library-роль (run) + standalone-роль (CLI-блок).
+  process.exitCode = await runRuleCli(import.meta.dirname)
+}

package/rules/npm-module/docs/fix.md

@@ -12,15 +12,15 @@ docgen:
 ## Поведінка
 
 1. Запуск правила.
-    *   Приймає контекст прогону.
-    *   Виконує застосування JS-занепокоєних.
-    *   Застосовує політику.
-    *   Генерує посилання MDC.
-    *   Повертає результат прогону.
+   - Приймає контекст прогону.
+   - Виконує застосування JS-занепокоєних.
+   - Застосовує політику.
+   - Генерує посилання MDC.
+   - Повертає результат прогону.
 2. Виконання у режимі CLI.
-    *   Виконується як автономний скрипт.
-    *   Виконує повний еквівалент команди `npx @nitra/cursor fix <id>`.
-    *   Повертає код виходу з процесу.
+   - Виконується як автономний скрипт.
+   - Виконує повний еквівалент команди `npx @nitra/cursor fix <id>`.
+   - Повертає код виходу з процесу.
 
 ## Публічний API
 

package/rules/npm-module/docs/index.md

@@ -6,6 +6,7 @@ resource: npm/rules/npm-module/
 
 # npm/rules/npm-module
 
-| Файл | Тип |
-|---|---|
-| [fix.mjs](fix.md) | JS Module |
+| Файл                | Тип       |
+| ------------------- | --------- |
+| [fix.mjs](fix.md)   | JS Module |
+| [main.mjs](main.md) | JS Module |

package/rules/npm-module/docs/main.md

@@ -0,0 +1,29 @@
+---
+type: JS Module
+title: main.mjs
+resource: npm/rules/npm-module/main.mjs
+docgen:
+  crc: 762b6875
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+---
+
+## Огляд
+
+Модуль виконує перевірку, застосовуючи політику, обробляючи JS-запити. При запуску як інструмент командного рядка, метод `run` ініціює повний запуск правила. Цей запуск включає завантаження конфігурацій, що спираються на meta.json, застосування білих списків та підбиття підсумків. Модуль є Read-only, тобто не пише у ФС/БД. Кешування даних відбувається в межах одного прогону.
+
+## Поведінка
+
+1. Викликається функція `run` для виконання перевірки.
+2. Виконання перевірки включає застосування політики, обробку JS-запитань та посилання на MDC-референси.
+3. Якщо код виконується як окремий інструмент командного рядка, ініціюється повний запуск правила.
+4. Повний запуск правила включає завантаження конфігурацій, застосування білих списків та підбиття підсумків.
+
+## Публічний API
+
+run — виконує основну логіку правила: застосовує перевірки, обробляє JS-залежності, застосовує політику та посилання MDC.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).
+- Кешує результати в межах одного прогону.

package/rules/npm-module/js/docs/index.md

@@ -6,9 +6,9 @@ resource: npm/rules/npm-module/js/
 
 # npm/rules/npm-module/js
 
-| Файл | Тип |
-|---|---|
+| Файл                                            | Тип       |
+| ----------------------------------------------- | --------- |
 | [header_doc_pointer.mjs](header_doc_pointer.md) | JS Module |
-| [package_structure.mjs](package_structure.md) | JS Module |
-| [rule_meta.mjs](rule_meta.md) | JS Module |
-| [skill_meta.mjs](skill_meta.md) | JS Module |
+| [package_structure.mjs](package_structure.md)   | JS Module |
+| [rule_meta.mjs](rule_meta.md)                   | JS Module |
+| [skill_meta.mjs](skill_meta.md)                 | JS Module |

package/rules/npm-module/js/docs/rule_meta.md

@@ -3,31 +3,32 @@ type: JS Module
 title: rule_meta.mjs
 resource: npm/rules/npm-module/js/rule_meta.mjs
 docgen:
-  crc: 8262678c
+  crc: 938ccd0a
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 100
 ---
 
-Перевіряє наявність директорії npm/rules у вказаному шляху. Ітерує по всіх директоріях у директорії npm/rules. Для кожної директорії виконує перевірку наявності файлу auto.md та валідність полів auto та lint у конфігурації meta.json. Перевіряє наявність файлу js/lint.mjs у каталозі правила. Збирає результати валідації та повертає код виходу репортера.
+## Огляд
+
+Модуль перевіряє конфігурацію правил, розташованих у каталозі `npm/rules`. Він забезпечує наявність обов'язкового файлу `scripts.mdc` для кожного правила. Крім того, він валідує структуру метаданих у `meta.json`, перевіряючи відповідність полів, таких як `auto` та `lint`, визначеним контрактам. У процесі перевірки використовуються маркери повідомлень (scripts.mdc).
 
 ## Поведінка
 
-1. Перевірка наявності директорії npm/rules у вказаному шляху.
-2. Ітерація по всіх директоріях у директорії npm/rules.
-3. Для кожної директорії виконується перевірка правила.
-4. Перевірка наявності файлу auto.md у директорії правила.
-5. Перевірка валідності поля auto у meta.json правила.
-6. Перевірка наявності поля lint у meta.json правила.
-7. Перевірка валідності поля lint у meta.json правила.
-8. Перевірка наявності файлу js/lint.mjs у каталозі правила.
-9. Збір результатів валідації.
-10. Повернення коду виходу репортера.
+1. Викликати `check` для початку валідації.
+2. Перевірити наявність каталогу `npm/rules` у корені репозиторію. Якщо каталог відсутній, валідація завершується успішно.
+3. Для кожного підкаталогу у `npm/rules` (який представляє правило):
+   а. Перевірити наявність файлу `auto.md`. Якщо він присутній, реєструється помилка, оскільки метадані тепер знаходяться у `meta.json`.
+   б. Перевірити наявність файлу `<id>.mdc` у каталозі правила. Якщо він відсутній, реєструється помилка, оскільки це обов'язковий файл (scripts.mdc).
+   в. Зчитати вміст `meta.json` правила. Якщо файл відсутній або невалідний, реєструється помилка, і перевірка цього правила припиняється.
+   г. Перевірити поле `auto` у `meta.json`. Якщо поле `auto` присутнє, воно повинно бути валідним (відповідати одному з визначених форматів, або бути відсутнім). Якщо поле `auto` містить невідомий предикат, реєструється помилка.
+   ґ. Перевірити поле `lint` у `meta.json`. Якщо поле `lint` присутнє, воно повинно бути валідним (відповідати "per-file" або "full"). Також перевіряється, чи експортує файл `main.mjs` у каталозі правила функцію `lint` відповідно до зазначеного значення `lint`.
+   і. Якщо всі перевірки для правила пройшли успішно, реєструється повідомлення про валідність `meta.json`.
+4. Після обробки всіх правил, повертається код виходу, що відображає загальний статус валідації.
 
 ## Публічний API
 
-check — Валідує всі `npm/rules/<id>/meta.json`.
+check — перевіряє відповідність усіх файлів `npm/rules/<id>/meta.json` встановленим критеріям.
 
 ## Гарантії поведінки
 
-- Read-only: файл не виконує операцій запису у файлову систему.
-- За невдачі повертає значення помилки (`false`/`null`/`Err`) замість генерування винятку чи паніки.
-- Не звертається до мережі.
+- Read-only: не виконує операцій запису (ФС/БД).

package/rules/npm-module/js/header_doc_pointer.mjs

@@ -47,9 +47,7 @@ function moduleJsDoc(source) {
  * @returns {boolean} true для звичайних source-файлів
  */
 function isSourceMjs(fileEntry) {
-  return (
-    fileEntry.isFile() && fileEntry.name.endsWith('.mjs') && !fileEntry.name.endsWith('.test.mjs')
-  )
+  return fileEntry.isFile() && fileEntry.name.endsWith('.mjs') && !fileEntry.name.endsWith('.test.mjs')
 }
 
 /**

package/rules/npm-module/js/rule_meta.mjs

@@ -1,5 +1,5 @@
 /** @see ./docs/rule_meta.md */
-import { existsSync, readdirSync } from 'node:fs'
+import { existsSync, readdirSync, readFileSync } from 'node:fs'
 import { join } from 'node:path'
 
 import { createCheckReporter } from '../../../scripts/lib/check-reporter.mjs'
@@ -41,8 +41,12 @@ function checkLintField(id, ruleDir, raw, reporter) {
     reporter.fail(`rules/${id}: meta.json.lint нерозпізнане (очікується "per-file"|"full")`)
     return false
   }
-  if (!existsSync(join(ruleDir, 'js', 'lint.mjs'))) {
-    reporter.fail(`rules/${id}: lint:"${raw.lint}" але немає js/lint.mjs`)
+  const mainPath = join(ruleDir, 'main.mjs')
+  const src = existsSync(mainPath) ? readFileSync(mainPath, 'utf8') : ''
+  // Канон (ADR 2026-06-21): lint-поверхня — це експорт `lint` із `main.mjs` (інлайн або
+  // `export { lint } from './js/…'`), а не окремий `js/lint.mjs`.
+  if (!/export\s+(?:async\s+)?function\s+lint\b|export\s*\{[^}]*\blint\b/u.test(src)) {
+    reporter.fail(`rules/${id}: lint:"${raw.lint}" але main.mjs не експортує lint`)
     return false
   }
   return true
@@ -63,6 +67,12 @@ function checkRule(id, ruleDir, reporter) {
     ruleOk = false
   }
 
+  // Канон (scripts.mdc): {rule}.mdc — ОБОВ'ЯЗКОВИЙ у кожному npm/rules/<id>/.
+  if (!existsSync(join(ruleDir, `${id}.mdc`))) {
+    reporter.fail(`rules/${id}: відсутній ${id}.mdc — обов'язковий (scripts.mdc)`)
+    ruleOk = false
+  }
+
   const raw = readRuleMetaRaw(ruleDir)
   if (!raw) {
     reporter.fail(`rules/${id}: відсутній або невалідний meta.json`)

package/rules/npm-module/main.mjs

@@ -0,0 +1,20 @@
+import { isRunAsCli, runRuleCli } from '../../scripts/lib/run-rule-cli.mjs'
+import { runStandardRule } from '../../scripts/lib/run-standard-rule.mjs'
+
+/**
+ * Єдиний entrypoint правила (ADR 2026-06-21). `run()` — check-поверхня: applies →
+ * JS-concerns → policy → mdc-refs (через runStandardRule). Lint-поверхні правило не має
+ * (`meta.json` без `lint`), тож експорту `lint` тут немає.
+ * Library mode: викликається CLI orchestration через `import + run(ctx)`.
+ * @param {import('../../scripts/lib/run-standard-rule.mjs').RuleContext} [ctx] контекст прогону (walkCache тощо)
+ * @returns {Promise<number>} 0 — OK, 1 — порушення
+ */
+export function run(ctx) {
+  return runStandardRule(import.meta.dirname, ctx)
+}
+
+if (isRunAsCli(import.meta.url)) {
+  // Standalone: bun rules/<id>/main.mjs — повний еквівалент `npx @nitra/cursor check <id>`
+  // (config-loading + whitelist + summary): library-роль (run) + standalone-роль (CLI-блок).
+  process.exitCode = await runRuleCli(import.meta.dirname)
+}

package/rules/php/docs/fix.md

@@ -14,14 +14,14 @@ docgen:
 ## Поведінка
 
 1. Запуск правила.
-    *   Приймає контекст прогону.
-    *   Виконує застосування JS-занепокоєних до політики до mdc-refs.
-    *   Повертає результат прогону.
+   - Приймає контекст прогону.
+   - Виконує застосування JS-занепокоєних до політики до mdc-refs.
+   - Повертає результат прогону.
 
 2. Запуск у режимі CLI.
-    *   Виконується при запуску через CLI.
-    *   Виконує повний еквівалент команди `npx @nitra/cursor fix <id>`.
-    *   Повертає код виходу.
+   - Виконується при запуску через CLI.
+   - Виконує повний еквівалент команди `npx @nitra/cursor fix <id>`.
+   - Повертає код виходу.
 
 ## Публічний API
 

package/rules/php/docs/index.md

@@ -6,6 +6,7 @@ resource: npm/rules/php/
 
 # npm/rules/php
 
-| Файл | Тип |
-|---|---|
-| [fix.mjs](fix.md) | JS Module |
+| Файл                | Тип       |
+| ------------------- | --------- |
+| [fix.mjs](fix.md)   | JS Module |
+| [main.mjs](main.md) | JS Module |

package/rules/php/docs/main.md

@@ -0,0 +1,33 @@
+---
+type: JS Module
+title: main.mjs
+resource: npm/rules/php/main.mjs
+docgen:
+  crc: a2c44b0c
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+---
+
+## Огляд
+
+Скрипт виконує перевірку коду відповідно до правила `php.mdc`. Він запускає `composer audit` для перевірки залежностей, а також, якщо встановлені, виконує PHPStan, Psalm, PHP-CS-Fixer (у режимі dry-run) та PHPCS зі стандартом Security. Робота скрипта ґрунтується на конфігурації, визначеній у `composer.json`. Скрипт пропускає запуск інструменту, якщо відповідний виконуваний файл відсутній у `vendor/bin/`. Якщо `composer.json` відсутній у корені, інструменти не запускаються.
+
+## Поведінка
+
+run виконує стандартну перевірку, застосовуючи правила до контексту.
+getPhpcsCodePaths визначає шляхи до каталогів коду для PHPCS, перевіряючи типові директорії (`app`, `src`, `lib`, `public`, `www`) або кореневий каталог.
+runPhpLintSteps виконує послідовність перевірок: `composer audit`, PHP-CS-Fixer (dry-run), phpcs (Security), PHPStan та Psalm, пропускаючи кроки, якщо відповідні інструменти відсутні.
+lint оркеструє виконання кроків PHP-лінтування для всього репозиторію.
+
+## Публічний API
+
+run — головна точка входу для виконання правил (перевірка логіки застосування до JS-задач, політик та посилань MDC).
+getPhpcsCodePaths — Визначає шляхи до коду, які має аналізувати PHPCS.
+runPhpLintSteps — Виконує етапи лінтингу, включаючи аудит `composer`, `php-cs-fixer`, `phpstan` та `psalm`.
+lint — Координує фазу лінтингу, виконуючи аудит `composer`, перевірку стилю коду (`php-cs-fixer`) та аналіз статичних аналізаторів (`phpstan`/`psalm`).
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).
+- Кешує результати в межах одного прогону.
+- Свідомо пропускає шляхи: `.git`, `node_modules`.

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

@@ -6,7 +6,7 @@ resource: npm/rules/php/js/
 
 # npm/rules/php/js
 
-| Файл | Тип |
-|---|---|
-| [lint.mjs](lint.md) | JS Module |
+| Файл                      | Тип       |
+| ------------------------- | --------- |
+| [lint.mjs](lint.md)       | JS Module |
 | [tooling.mjs](tooling.md) | JS Module |

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

@@ -3,25 +3,25 @@ type: JS Module
 title: tooling.mjs
 resource: npm/rules/php/js/tooling.mjs
 docgen:
-  crc: a3e6a475
-  score: 95
+  crc: 22a05733
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
 ---
 
-Огляд
-Файл перевіряє наявність конфігураційних файлів для визначення залежностей та робочих потоків. Файл використовується для встановлення наявності певних файлів у репозиторії.
+Модуль перевіряє наявність ключових конфігураційних файлів проєкту, а саме `composer.json` та `package.json`. Перевірка здійснюється за допомогою публічної функції `check`. Мета — підтвердити наявність базових файлів, необхідних для роботи проєкту (php.mdc).
 
 ## Поведінка
 
-1. Перевірити наявність composer.json
-2. Перевірити наявність package.json
-3. Перевірити наявність .github/workflows/lint-php.yml
+1. Перевіряє наявність файлу `composer.json` у корені проєкту. Якщо файл відсутній, повідомляє про відсутність `composer.json` (php.mdc).
+2. Перевіряє наявність файлу `package.json` у корені проєкту. Якщо файл відсутній, повідомляє про відсутність `package.json` (php.mdc).
+3. Перевіряє наявність файлу `.github/workflows/lint-php.yml`. Якщо файл відсутній, повідомляє про необхідність створити його згідно з `php.mdc`.
+4. Повертає код виходу, який вказує на успішне виконання (0) або наявність проблем (1).
 
 ## Публічний API
 
-check — Перевіряє відповідність проєкту правилам php.mdc.
+check — перевіряє відповідність проєкту стандартам php.mdc.
 
 ## Гарантії поведінки
 
-- Read-only: файл не виконує операцій запису у файлову систему.
+- Read-only: не виконує операцій запису (ФС/БД).
 - Свідомо пропускає шляхи: `.github`, `.git`.
-- Не звертається до мережі.

package/rules/php/{lint/lint.mjs → main.mjs}

@@ -12,9 +12,22 @@ import { spawnSync } from 'node:child_process'
 import { existsSync, statSync } from 'node:fs'
 import { join, resolve } from 'node:path'
 
-import { isRunAsCli } from '../../../scripts/cli-entry.mjs'
-import { createCheckReporter } from '../../../scripts/lib/check-reporter.mjs'
-import { resolveCmd } from '../../../scripts/utils/resolve-cmd.mjs'
+import { isRunAsCli } from '../../scripts/cli-entry.mjs'
+import { createCheckReporter } from '../../scripts/lib/check-reporter.mjs'
+import { resolveCmd } from '../../scripts/utils/resolve-cmd.mjs'
+import { runStandardLint } from '../../scripts/lib/run-standard-lint.mjs'
+import { runRuleCli } from '../../scripts/lib/run-rule-cli.mjs'
+import { runStandardRule } from '../../scripts/lib/run-standard-rule.mjs'
+
+/**
+ * Єдиний entrypoint правила (ADR 2026-06-21). `run()` — check-поверхня (applies → JS-concerns
+ * → policy → mdc-refs); `lint()` нижче — lint-поверхня (composer/phpstan/psalm), імпл інлайн тут.
+ * @param {import('../../scripts/lib/run-standard-rule.mjs').RuleContext} [ctx] контекст прогону
+ * @returns {Promise<number>} 0 — OK, 1 — порушення
+ */
+export function run(ctx) {
+  return runStandardRule(import.meta.dirname, ctx)
+}
 
 const PHPCS_CODE_DIR_CANDIDATES = ['app', 'src', 'lib', 'public', 'www']
 
@@ -62,11 +75,11 @@ function runTool(label, abs, args, pass, fail) {
 }
 
 /**
- * Запускає `lint-php`.
+ * Запускає кроки `lint-php` (composer audit + php-cs-fixer/phpcs/phpstan/psalm).
  * @param {string} [cwd] корінь репозиторію
  * @returns {number} 0 — OK, 1 — є помилки
  */
-export function run(cwd = process.cwd()) {
+export function runPhpLintSteps(cwd = process.cwd()) {
   const reporter = createCheckReporter()
   const { pass, fail } = reporter
 
@@ -121,6 +134,19 @@ export function run(cwd = process.cwd()) {
   return reporter.getExitCode()
 }
 
+/**
+ * Оркестраторний адаптер `n-cursor lint php` (лінтер-фаза): composer audit + php-cs-fixer
+ * (`--dry-run`) + phpstan/psalm через `run` у `runStandardLint` (лок). Read-only — мутацій
+ * немає, тож `opts` ігнорується. Структурні php.mdc-перевірки — у конформність-фазі.
+ * @param {string[] | undefined} _files ігнорується (whole-repo обхід)
+ * @param {string} [cwd] корінь
+ * @returns {Promise<number>} exit code
+ */
+export function lint(_files, cwd = process.cwd()) {
+  return runStandardLint(import.meta.dirname, () => runPhpLintSteps(cwd))
+}
+
 if (isRunAsCli(import.meta.url)) {
-  process.exitCode = run()
+  // Standalone: bun rules/php/main.mjs — повний еквівалент `npx @nitra/cursor check php`.
+  process.exitCode = await runRuleCli(import.meta.dirname)
 }

package/rules/python/docs/fix.md

@@ -12,19 +12,19 @@ docgen:
 ## Поведінка
 
 1. Запуск правила.
-    *   Приймає контекст прогону.
-    *   Виконує застосування JS-занепокоєних.
-    *   Застосовує політику.
-    *   Генерує посилання на MDC.
-    *   Повертає результат прогону.
+   - Приймає контекст прогону.
+   - Виконує застосування JS-занепокоєних.
+   - Застосовує політику.
+   - Генерує посилання на MDC.
+   - Повертає результат прогону.
 
 2. Виконання у режимі CLI.
-    *   Виконується як автономний скрипт.
-    *   Виконує повний еквівалент команди `npx @nitra/cursor fix <id>`.
-    *   Виконує завантаження конфігурації.
-    *   Виконує перевірку дозволів.
-    *   Виконує підбирання списку.
-    *   Виконує підбирання резюме.
+   - Виконується як автономний скрипт.
+   - Виконує повний еквівалент команди `npx @nitra/cursor fix <id>`.
+   - Виконує завантаження конфігурації.
+   - Виконує перевірку дозволів.
+   - Виконує підбирання списку.
+   - Виконує підбирання резюме.
 
 ## Публічний API
 

package/rules/python/docs/index.md

@@ -6,6 +6,7 @@ resource: npm/rules/python/
 
 # npm/rules/python
 
-| Файл | Тип |
-|---|---|
-| [fix.mjs](fix.md) | JS Module |
+| Файл                | Тип       |
+| ------------------- | --------- |
+| [fix.mjs](fix.md)   | JS Module |
+| [main.mjs](main.md) | JS Module |

package/rules/python/docs/main.md

@@ -0,0 +1,31 @@
+---
+type: JS Module
+title: main.mjs
+resource: npm/rules/python/main.mjs
+docgen:
+  crc: 8ceba96a
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 90
+---
+
+## Огляд
+
+Виконує логіку `lint-python` за правилом `python.mdc` для забезпечення якості коду Python. Якщо файл `pyproject.toml` відсутній у корені, виконання завершується з кодом 0. Якщо файл присутній, але `uv` не знайдено у системному шляху, це вважається помилкою, оскільки `uv` є єдиним дозволеним пакет-менеджером (без Poetry). Для роботи необхідно виконати `uv lock --check` для підтвердження актуальності файлу блокування та `uv sync --frozen` для створення середовища, що відповідає `uv.lock` (детальніше про `uv` на https://docs.astral.sh/uv/). Опціональні лінтери запускаються лише за умови їх доступності через `uv run`. Запускаються `ruff` у режимі автоматичного виправлення (`--fix`) та форматування, а також `mypy` для статичного аналізу коду, використовуючи канонічний патерн серіалізації через `runStandardLint`.
+
+## Поведінка
+
+run виконує стандартну перевірку на основі контексту.
+runLintPythonSteps виконує послідовність кроків лінтування Python, включаючи перевірку `pyproject.toml`, виконання `uv lock --check` та `uv sync --frozen`, а також запуск опціональних лінтерів (`ruff`, `mypy`) через `uv run`.
+runLintPython запускає послідовність кроків лінтування Python, використовуючи механізм стандартного лінтування.
+lint оркеструє запуск `runLintPython` для аналізу всього проєкту.
+
+## Публічний API
+
+run — Основна точка входу для виконання правил, що включає перевірку логіки застосування (JS-concerns → policy → mdc-refs) та виконання лінтингу.
+runLintPythonSteps — Виконує внутрішні етапи лінтингу для Python без збереження логів.
+runLintPython — Публічний інтерфейс для запуску лінтингу Python, що забезпечує унікальність виконання через блокування та аналіз стану репозиторію.
+lint — Координатор, який ініціює запуск лінтингу Python, делегуючи це `runLintPython`.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).

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

@@ -6,8 +6,8 @@ resource: npm/rules/python/js/
 
 # npm/rules/python/js
 
-| Файл | Тип |
-|---|---|
+| Файл                      | Тип       |
+| ------------------------- | --------- |
 | [applies.mjs](applies.md) | JS Module |
-| [lint.mjs](lint.md) | JS Module |
+| [lint.mjs](lint.md)       | JS Module |
 | [tooling.mjs](tooling.md) | JS Module |

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

@@ -3,32 +3,32 @@ type: JS Module
 title: tooling.mjs
 resource: npm/rules/python/js/tooling.mjs
 docgen:
-  crc: f4dc22e2
-  score: 95
+  crc: fcabec1d
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
 ---
 
-Файл виконує перевірку наявності конфігураційних та залежностей у кореневому каталозі репозиторію. Він перевіряє структуру проекту відповідно до вимог, визначених у package.json.
+Модуль перевіряє відповідність структури проєкту вимогам, визначеним у `python.mdc`. Він перевіряє наявність ключових файлів конфігурації, таких як `pyproject.toml`, `uv.lock` та `package.json`, у корені репозиторію. Мета — підтвердити відповідність проєкту встановленим стандартам, зокрема щодо використання `uv` замість Poetry.
+
+Поведінка
+Виконує перевірку за допомогою публічної функції `check`. Ігнорує шляхи `.github` та `.git`. Не виконує операцій запису у файлову систему чи бази даних (Read-only). (python.mdc)
 
 ## Поведінка
 
-1. Перевірити наявність `pyproject.toml` у корені репозиторію.
-2. Перевірити наявність `uv.lock` у корені репозиторію.
-3. Якщо `uv.lock` відсутній, повернути код виходу.
-4. Перевірити наявність `poetry.lock` у корені репозиторію.
-5. Якщо `poetry.lock` знайдено, повернути помилку.
-6. Якщо `poetry.lock` відсутній, пропустити.
-7. Перевірити наявність `package.json` у корені репозиторію.
-8. Якщо `package.json` відсутній, повернути помилку.
-9. Перевірити наявність файлу `.github/workflows/lint-python.yml` у корені репозиторію.
-10. Якщо файлу `.github/workflows/lint-python.yml` немає, повернути помилку.
-11. Повернути код виходу.
+1. Перевіряє відповідність проєкту правилам (python.mdc) у вказаному корені репозиторію.
+2. Якщо файл `pyproject.toml` відсутній у корені, повертає код виходу, що вказує на відсутність конфігурації.
+3. Перевіряє наявність файлу `uv.lock`. Якщо він відсутній, повідомляє про необхідність згенерувати його за допомогою `uv lock` (python.mdc).
+4. Перевіряє відсутність файлів `poetry.lock` та `poetry.toml`. Якщо будь-який із них знайдено, повідомляє про необхідність відмови від Poetry та міграції на `uv` (python.mdc).
+5. Перевіряє наявність файлу `package.json` у корені. Якщо він відсутній, повідомляє про необхідність його додавання (python.mdc).
+6. Перевіряє наявність файлу `.github/workflows/lint-python.yml` у корені. Якщо він відсутній, повідомляє про необхідність його створення згідно з документацією (python.mdc).
+7. Повертає код виходу, що відображає загальний стан перевірки.
+8. Не перевіряє шляхи, що містять `.github` або `.git`.
 
 ## Публічний API
 
-check — Перевіряє відповідність проєкту правилам python.mdc.
+check — перевіряє відповідність проєкту стандартам python.mdc.
 
 ## Гарантії поведінки
 
-- Read-only: файл не виконує операцій запису у файлову систему.
+- Read-only: не виконує операцій запису (ФС/БД).
 - Свідомо пропускає шляхи: `.github`, `.git`.
-- Не звертається до мережі.

package/rules/python/{lint/lint.mjs → main.mjs}

@@ -24,10 +24,22 @@ import { spawnSync } from 'node:child_process'
 import { existsSync } from 'node:fs'
 import { join } from 'node:path'
 
-import { isRunAsCli } from '../../../scripts/cli-entry.mjs'
-import { createCheckReporter } from '../../../scripts/lib/check-reporter.mjs'
-import { resolveCmd } from '../../../scripts/utils/resolve-cmd.mjs'
-import { runStandardLint } from '../../../scripts/lib/run-standard-lint.mjs'
+import { isRunAsCli } from '../../scripts/cli-entry.mjs'
+import { createCheckReporter } from '../../scripts/lib/check-reporter.mjs'
+import { resolveCmd } from '../../scripts/utils/resolve-cmd.mjs'
+import { runStandardLint } from '../../scripts/lib/run-standard-lint.mjs'
+import { runRuleCli } from '../../scripts/lib/run-rule-cli.mjs'
+import { runStandardRule } from '../../scripts/lib/run-standard-rule.mjs'
+
+/**
+ * Єдиний entrypoint правила (ADR 2026-06-21). `run()` — check-поверхня (applies → JS-concerns
+ * → policy → mdc-refs); `lint()` нижче — lint-поверхня (uv/ruff/mypy), імпл інлайн тут.
+ * @param {import('../../scripts/lib/run-standard-rule.mjs').RuleContext} [ctx] контекст прогону
+ * @returns {Promise<number>} 0 — OK, 1 — порушення
+ */
+export function run(ctx) {
+  return runStandardRule(import.meta.dirname, ctx)
+}
 
 /**
  * Запускає CLI-крок і репортить результат.
@@ -103,7 +115,8 @@ export function runLintPythonSteps(cwd = process.cwd(), opts = {}) {
   const ruffCheck = readOnly ? ['check', '.'] : ['check', '--fix', '.']
   const ruffFormat = readOnly ? ['format', '--check', '.'] : ['format', '.']
   if (!runOptionalUvTool('ruff', readOnly ? 'ruff check' : 'ruff check --fix', ruffCheck)) return reporter.getExitCode()
-  if (!runOptionalUvTool('ruff', readOnly ? 'ruff format --check' : 'ruff format', ruffFormat)) return reporter.getExitCode()
+  if (!runOptionalUvTool('ruff', readOnly ? 'ruff format --check' : 'ruff format', ruffFormat))
+    return reporter.getExitCode()
   if (!runOptionalUvTool('mypy', 'mypy', ['.'])) return reporter.getExitCode()
 
   return reporter.getExitCode()
@@ -117,6 +130,18 @@ export function runLintPythonSteps(cwd = process.cwd(), opts = {}) {
 export const runLintPython = (opts = {}) =>
   runStandardLint(import.meta.dirname, () => runLintPythonSteps(process.cwd(), opts))
 
+/**
+ * Оркестраторний адаптер `n-cursor lint python`: делегує у `runLintPython`.
+ * @param {string[] | undefined} _files ігнорується (whole-project аналіз)
+ * @param {string} [_cwd] корінь (CLI бере process.cwd())
+ * @param {{ readOnly?: boolean }} [opts] readOnly → ruff без `--fix`, format `--check`
+ * @returns {Promise<number>} exit code
+ */
+export function lint(_files, _cwd, opts = {}) {
+  return runLintPython({ readOnly: opts.readOnly === true })
+}
+
 if (isRunAsCli(import.meta.url)) {
-  process.exitCode = await runLintPython({ readOnly: process.argv.includes('--read-only') })
+  // Standalone: bun rules/python/main.mjs — повний еквівалент `npx @nitra/cursor check python`.
+  process.exitCode = await runRuleCli(import.meta.dirname)
 }