@nitra/cursor 5.3.3 → 5.4.0

package/rules/doc-files/lint/lint.mjs

@@ -0,0 +1,105 @@
+/**
+ * CLI-обгортка канонічного `lint-doc-files` (doc-files.mdc): детермінований детектор
+ * застарілості файлових док (`<dir>/docs/<stem>.md`) — 0 викликів LLM, працює будь-де.
+ *
+ * Режими (мапа команд у doc-files.mdc / спеці 2026-06-12):
+ *  - (без прапорців) / `[paths…]` — повний або точковий детект; **exit 1**, якщо є stale.
+ *  - `--missing-only`             — звужує до `missing` (без `crc-mismatch`); exit 1.
+ *  - `--json`                     — JSON-лістинг усіх кандидатів зі станом (= старий `scan`); exit 0.
+ *  - `--hook` / `--git` / `--degraded` — делегат у `runDocFilesCheckCli` (hook-протокол: exit 2/0).
+ *
+ * Серіалізація: повний прогін — через `runStandardLint` (ключ `lint-doc-files`,
+ * виводиться зі шляху каталогу). Hook/git/degraded форми — **без локу** (швидкі точкові
+ * перевірки в hook-протоколі потребують завжди-свіжого вердикту) — канон scripts.mdc.
+ */
+import { existsSync, statSync } from 'node:fs'
+import { join, relative, resolve, sep, isAbsolute } from 'node:path'
+
+import { isRunAsCli } from '../../../scripts/cli-entry.mjs'
+import { runStandardLint } from '../../../scripts/lib/run-standard-lint.mjs'
+import {
+  describeFile,
+  isDocCandidate,
+  resolveRoot,
+  runDocFilesCheckCli,
+  runDocFilesScanCli,
+  scanForDocFiles
+} from '../js/docgen-scan.mjs'
+
+/**
+ * Нормалізує шлях-кандидат до posix-шляху від кореня (null поза деревом).
+ * @param {string} root абсолютний корінь
+ * @param {string} candidate шлях-кандидат
+ * @returns {string|null} posix-шлях від кореня або null
+ */
+function toRelSource(root, candidate) {
+  const rel = relative(root, resolve(root, candidate))
+  if (rel.startsWith('..') || isAbsolute(rel)) return null
+  return rel.split(sep).join('/')
+}
+
+/**
+ * Витягує позиційні шляхи з argv (не прапорці й не значення `--root`).
+ * @param {string[]} argv аргументи
+ * @returns {string[]} позиційні шляхи
+ */
+function positionalPaths(argv) {
+  const rootIdx = argv.indexOf('--root')
+  const skip = rootIdx !== -1 ? rootIdx + 1 : -1
+  return argv.filter((a, i) => !a.startsWith('--') && i !== skip)
+}
+
+/**
+ * Реальна робота повного / точкового детекту. Exit 1 — є stale, 0 — все свіже.
+ * @param {string[]} argv аргументи після назви команди
+ * @returns {number} exit-код
+ */
+export function runLintDocFilesSteps(argv) {
+  const root = resolveRoot(argv)
+  if (!existsSync(root) || !statSync(root).isDirectory()) {
+    console.error(`lint-doc-files: корінь не існує або не є директорією: ${root}`)
+    return 1
+  }
+  const missingOnly = argv.includes('--missing-only')
+  const paths = positionalPaths(argv)
+
+  const described = paths.length
+    ? paths
+        .map(p => toRelSource(root, p))
+        .filter(rel => rel && isDocCandidate(root, rel) && existsSync(join(root, rel)))
+        .map(rel => describeFile(root, /** @type {string} */ (rel)))
+    : scanForDocFiles(root)
+
+  let stale = described.filter(f => f.stale)
+  if (missingOnly) stale = stale.filter(f => f.reason === 'missing')
+
+  if (stale.length === 0) {
+    console.log('✓ doc-files: усі файлові доки актуальні.')
+    return 0
+  }
+  const list = stale.map(f => `  - ${f.sourcePath} (${f.reason})`).join('\n')
+  console.error(
+    `✗ doc-files: документація застаріла/відсутня для ${stale.length} файл(ів):\n${list}\n→ перегенеруй: npx @nitra/cursor fix-doc-files`
+  )
+  return 1
+}
+
+/**
+ * Публічна CLI-форма `lint-doc-files`. Hook/git/degraded — делегат без локу; `--json` —
+ * scan; решта — повний/точковий детект під `runStandardLint` (ключ `lint-doc-files`).
+ * @param {string[]} [argv] аргументи після назви команди
+ * @returns {Promise<number>} exit-код
+ */
+export function runLintDocFilesCli(argv = process.argv.slice(3)) {
+  if (argv.includes('--hook') || argv.includes('--git') || argv.includes('--degraded')) {
+    return runDocFilesCheckCli(argv)
+  }
+  if (argv.includes('--json')) {
+    return Promise.resolve(runDocFilesScanCli(argv))
+  }
+  return runStandardLint(import.meta.dirname, () => runLintDocFilesSteps(argv))
+}
+
+if (isRunAsCli(import.meta.url)) {
+  process.exitCode = await runLintDocFilesCli(process.argv.slice(2))
+}

package/rules/doc-files/meta.json

@@ -0,0 +1 @@
+{ "auto": "завжди", "lint": "quick" }

package/rules/docker/docs/fix.md

@@ -1,177 +1,37 @@
 ---
 docgen:
   source: npm/rules/docker/fix.mjs
-  crc: 12fc1644
+  crc: 38cf876b
+  score: 100
 ---
 
-# fix.mjs — entry-point правила `docker` (fix-режим)
+# fix.mjs
 
 ## Огляд
 
-Файл `npm/rules/docker/fix.mjs` — це тонкий **entry-point** правила `docker` у пакеті `@nitra/cursor` для режиму `fix` (автоматичне виправлення порушень). Він не містить власної логіки перевірки чи виправлень: уся реальна робота делегується у спільні бібліотечні функції з `npm/scripts/lib/`.
+Запуск правила приймає контекст прогону, застосовує JS-занепокоєні до політики до mdc-refs та повертає результат.
 
-Файл виконує **дві ролі** одночасно (патерн dual-role module, прийнятий в усіх `rules/<id>/fix.mjs` цього репозиторію):
+Виконання у режимі CLI виконує повний еквівалент команди `npx @nitra/cursor fix <id>`, включаючи завантаження конфігурації, перевірку дозволених елементів та підбиття підсумку.
 
-1. **Library role** — експортує іменовану функцію `run(ctx)`, яку викликає CLI-оркестратор `@nitra/cursor` (`bin/cursor.mjs` → `cmd-fix.mjs` / `cmd-fix-all.mjs`). У цьому режимі правило вбудовується в загальний прогін «всіх правил» зі спільним кешем обходу файлів (`walkCache`), агрегованим summary та глобальним whitelist.
-2. **Standalone role** — якщо файл запущений напряму (`bun npm/rules/docker/fix.mjs` або через `import.meta.url` як головний модуль), він виконується як автономний CLI-ентрі: завантажує конфіг, застосовує whitelist, друкує summary та повертає exit-code, повністю еквівалентний `npx @nitra/cursor fix docker`.
+## Поведінка
 
-Сам алгоритм виправлень розкладений у сусідніх теках цього правила (`js/`, `lint/`, `policy/`) і запускається уніфіковано через `runStandardRule`, яке прокручує чотири стандартні фази:
+1. Запуск правила.
+    *   Приймає контекст прогону.
+    *   Виконує застосування JS-занепокоєних до політики до mdc-refs.
+    *   Повертає результат.
 
-1. **applies** — перевірка, чи правило взагалі релевантне для поточного workspace.
-2. **JS-concerns** — JS-специфічні fix-перевірки (з теки `js/`).
-3. **policy** — політики/policy-перевірки правила.
-4. **mdc-refs** — узгодження посилань у файлі `docker.mdc` (опис правила для Cursor).
+2. Виконання у режимі CLI.
+    *   Викликається через оркестрацію CLI.
+    *   Виконує повний еквівалент команди `npx @nitra/cursor fix <id>`.
+    *   Виконує завантаження конфігурації, перевірку дозволених елементів та підбиття підсумку.
 
-ID правила (`docker`) визначається автоматично з імені директорії-носія через `import.meta.dirname` — у `fix.mjs` немає жодного хардкоду ID.
+## Публічний API
 
-## Експорти / API
+run — запускає правило: applies → JS-concerns → policy → mdc-refs (через runStandardRule).
+Library mode — викликається CLI orchestration через `import + run`.
 
-| Експорт     | Тип                      | Призначення                                                                                                                                    |
-| ----------- | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
-| `run(ctx?)` | named export, `function` | Library-API: запустити стандартний fix-pipeline правила `docker`. Повертає `Promise<number>` з exit-кодом (`0` — OK, `1` — порушення/помилка). |
+## Гарантії поведінки
 
-Інших іменованих або default-експортів файл не має.
-
-Окрім експорту, модуль містить **top-level side-effect-блок** (поза `run`), який спрацьовує лише коли файл є точкою входу процесу — див. секцію _Потік виконання_.
-
-### Сигнатура `run`
-
-```js
-export function run(ctx)
-```
-
-- **Параметри:**
-  - `ctx` _(optional)_ — об’єкт типу `RuleContext` (з `../../scripts/lib/run-standard-rule.mjs`). Передається оркестратором, коли правило запускають у складі загального прогону «всіх правил». Може містити, зокрема, спільний `walkCache` (для уникнення повторного `walk`/`glob` файлів кожним правилом), накопичений summary, прапори дебагу тощо.
-- **Повертає:** `Promise<number>` — exit-код прогону: `0` коли правило не знайшло порушень або успішно їх виправило, `1` коли лишились незавершені порушення чи виникла помилка.
-- **Side effects:** делегуються у `runStandardRule` — це може бути запис у файли проєкту (auto-fix), читання конфіга/файлів, запис у stdout/stderr (summary, прогрес-логи), а також модифікація переданого `ctx` (наприклад, заповнення `walkCache`).
-
-## Функції
-
-### `run(ctx)`
-
-**Сигнатура:** `export function run(ctx) → Promise<number>`
-
-**Призначення:** library-API правила `docker` для CLI-оркестратора `@nitra/cursor`. Виконує повний fix-pipeline правила: `applies → JS-concerns → policy → mdc-refs`.
-
-**Параметри:**
-
-- `ctx` — _(optional, об’єкт)_ контекст прогону, який передає зовнішній оркестратор. Тип описаний у JSDoc-import-посиланні `import('../../scripts/lib/run-standard-rule.mjs').RuleContext`. Може містити:
-  - `walkCache` — спільний кеш обходу/glob файлів, щоб правила не дублювали I/O;
-  - інші службові поля (summary-агрегатор, прапори, конфіг), залежно від реалізації `run-standard-rule.mjs`.
-  - Якщо викликати без аргументу, `runStandardRule` створить свій локальний контекст за замовчуванням.
-
-**Повертає:** `Promise<number>` — exit-код. За конвенцією репозиторію: `0` — порушень не знайдено / усе виправлено, `1` — лишились порушення або сталася помилка.
-
-**Side effects:** не виконує жодних побічних ефектів безпосередньо — лише повертає результат виклику `runStandardRule(import.meta.dirname, ctx)`. Усе I/O й auto-fix належить `runStandardRule` (читання файлів проєкту, потенційні модифікації файлів, запис у stdout, мутація `ctx.walkCache`).
-
-**Ключова деталь:** першим аргументом у `runStandardRule` передається `import.meta.dirname` — абсолютний шлях до теки, в якій лежить цей `fix.mjs`. Звідти `runStandardRule` витягує ID правила (`docker` — остання частина шляху) і завантажує підкомпоненти з `js/`, `lint/`, `policy/`. Завдяки цьому `fix.mjs` цілком універсальний і не містить літерала `"docker"`.
-
-## Залежності
-
-### Внутрішні (з самого пакета `@nitra/cursor`)
-
-| Імпорт            | Звідки                                    | Призначення                                                                                                                                     |
-| ----------------- | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
-| `isRunAsCli`      | `../../scripts/lib/run-rule-cli.mjs`      | Детектор «чи запущено цей файл як головний модуль процесу (CLI)». Зазвичай порівнює `import.meta.url` з `pathToFileURL(process.argv[1])`.       |
-| `runRuleCli`      | `../../scripts/lib/run-rule-cli.mjs`      | Standalone-обгортка: завантаження конфігу, застосування whitelist, друк summary, повернення exit-коду. Еквівалент `npx @nitra/cursor fix <id>`. |
-| `runStandardRule` | `../../scripts/lib/run-standard-rule.mjs` | Універсальний fix-pipeline правила: послідовно прогоняє фази `applies → JS-concerns → policy → mdc-refs`, читаючи реалізації з підтек правила.  |
-
-Розв’язання шляхів:
-
-- `../../scripts/lib/...` від `npm/rules/docker/fix.mjs` → `npm/scripts/lib/run-rule-cli.mjs` і `npm/scripts/lib/run-standard-rule.mjs`.
-
-### Зовнішні
-
-Власних `node:`/npm-залежностей файл не імпортує. Опосередковано (через `runStandardRule` і `runRuleCli`) використовуються стандартні модулі для роботи з FS/процесом, але до цього файлу це не належить.
-
-### Структурні залежності (runtime-конвенції)
-
-Хоч `fix.mjs` нічого з них не імпортує статично, для коректної роботи правила в директорії `npm/rules/docker/` мають існувати:
-
-- `meta.json` — метадані правила (ID, опис, applies-умови);
-- `docker.mdc` — Cursor rule-документ, на який звіряються mdc-refs;
-- `js/` — JS-специфічні fix-чеки правила (фаза _JS-concerns_);
-- `lint/` — lint-перевірки (читаються відповідним check-режимом);
-- `policy/` — policy-перевірки (фаза _policy_).
-
-`runStandardRule` сам шукає й підвантажує ці компоненти за `import.meta.dirname`.
-
-## Потік виконання / Використання
-
-### Сценарій 1 — Library mode (виклик з оркестратора)
-
-Так правило запускає `@nitra/cursor` під час команд типу `npx @nitra/cursor fix` (усі правила) або `npx @nitra/cursor fix docker` (одне правило, але через диспетчер):
-
-1. Оркестратор робить динамічний `import('npm/rules/docker/fix.mjs')`.
-2. Отримує функцію `run` з експортів.
-3. Підготовлює спільний `ctx` (наприклад, з `walkCache`) і викликає `await run(ctx)`.
-4. `run` повертає управління у `runStandardRule(import.meta.dirname, ctx)`, який:
-   - визначає ID правила як `basename(import.meta.dirname)` = `docker`;
-   - читає `meta.json` правила;
-   - виконує фазу `applies` — пропускає правило, якщо воно нерелевантне;
-   - запускає JS-concerns → policy → mdc-refs;
-   - повертає exit-код (`0`/`1`).
-5. Оркестратор додає результат до загального summary й переходить до наступного правила.
-
-Гілка `if (isRunAsCli(...))` у цьому сценарії **не виконується**, бо файл імпортовано як модуль, а не запущено напряму.
-
-### Сценарій 2 — Standalone mode (прямий запуск)
-
-Використовується розробником або IDE/CI-кроком напряму, без проходу через головний `bin/cursor.mjs`:
-
-```bash
-bun npm/rules/docker/fix.mjs
-# або
-node npm/rules/docker/fix.mjs
-```
-
-1. Node/Bun виконує файл як модуль-точку входу.
-2. Імпорти на верхньому рівні підтягують `isRunAsCli`, `runRuleCli`, `runStandardRule`.
-3. Експорт `run` реєструється (на випадок, якщо хтось одночасно імпортує цей файл).
-4. Виконується top-level блок:
-
-   ```js
-   if (isRunAsCli(import.meta.url)) {
-     process.exit(await runRuleCli(import.meta.dirname))
-   }
-   ```
-
-   - `isRunAsCli(import.meta.url)` повертає `true`, бо файл є головним модулем процесу.
-   - `await runRuleCli(import.meta.dirname)` виконує повноцінний standalone-pipeline: завантаження конфіга, whitelist, виклик внутрішнього аналогу `run` (тобто `runStandardRule`), друк summary.
-   - `process.exit(<code>)` завершує процес із отриманим exit-кодом, щоб CI / IDE могли правильно інтерпретувати успіх/помилку.
-
-5. Коментарі в коді явно фіксують виняток ESLint: `n/no-process-exit` і `unicorn/no-process-exit` свідомо вимкнено саме для цього рядка, бо standalone-ентрі **зобов’язаний** повертати exit-код процесу.
-
-### Інваріанти / контракти
-
-- ID правила завжди дорівнює імені теки, де лежить `fix.mjs` (тут — `docker`). Хардкод відсутній — переміщення в іншу теку автоматично змінить ID, тому файл не можна копіювати без перейменування теки.
-- `run` має лишатися **named export** `run` (не default) — оркестратор шукає саме це ім’я.
-- Top-level `await runRuleCli(...)` працює завдяки тому, що файл є ES-модулем (`.mjs`) із підтримкою top-level await.
-- Гілка `isRunAsCli` повинна лишатися **єдиним** side-effect блоком на верхньому рівні; будь-яка інша робота на модульному рівні зламає library mode.
-
-## Rebuild Test
-
-З цієї документації можна реконструювати файл-еквівалент:
-
-```js
-import { isRunAsCli, runRuleCli } from '../../scripts/lib/run-rule-cli.mjs'
-import { runStandardRule } from '../../scripts/lib/run-standard-rule.mjs'
-
-/**
- * Запускає правило: applies → JS-concerns → policy → mdc-refs.
- * Library mode: викликається CLI orchestration через `import + run(ctx)`.
- * @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)
-}
-
-if (isRunAsCli(import.meta.url)) {
-  // Standalone-ентрі: повний еквівалент `npx @nitra/cursor fix <id>`.
-  // eslint-disable-next-line n/no-process-exit
-  process.exit(await runRuleCli(import.meta.dirname))
-}
-```
-
-Семантично та функціонально такий код тотожний оригіналу: дві ролі модуля (library `run` + standalone main), делегування у `runStandardRule`/`runRuleCli`, ID правила визначається через `import.meta.dirname`, exit-код процесу повертається лише у standalone-режимі.
+- Read-only: файл не виконує операцій запису у файлову систему.
+- Кешує результати в межах одного прогону.
+- Не звертається до мережі.

package/rules/efes/docs/fix.md

@@ -1,210 +1,39 @@
 ---
 docgen:
   source: npm/rules/efes/fix.mjs
-  crc: 12fc1644
+  crc: 38cf876b
+  score: 100
 ---
 
-# `fix.mjs` — entry-point правила `efes`
+# fix.mjs
 
 ## Огляд
 
-Файл `npm/rules/efes/fix.mjs` — це **уніфікований entry-point** одного з правил пакету `@nitra/cursor` (правило `efes`, директорія `npm/rules/efes/`). Він виконує дві ролі одночасно:
+Виконує застосування політики JS-занепокоєних та політики на наданому контексті прогону, генеруючи посилання MDC та повертаючи результат.
 
-1. **Library mode** — експортує функцію `run(ctx)`, яку викликає CLI-оркестратор `@nitra/cursor` (через динамічний `import` модуля та виклик `run()` із підготовленим контекстом).
-2. **Standalone mode** — якщо файл запущено напряму (наприклад, `bun npm/rules/efes/fix.mjs`), він виконує повний CLI-цикл правила (завантаження конфігу, whitelist, summary), еквівалентний `npx @nitra/cursor fix efes`, і завершує процес із відповідним exit-кодом для CI/IDE.
+Виконується при запуску через командний рядок, виконуючи повний еквівалент команди `npx @nitra/cursor fix <id>` та повертаючи код виходу.
 
-Сам файл навмисно мінімальний — уся реальна логіка (виконання `applies → JS-concerns → policy → mdc-refs`) делегована у спільну бібліотечну функцію `runStandardRule`, що живе у `npm/scripts/lib/run-standard-rule.mjs`. Тому цей файл слугує лише **тонкою обгорткою (shim)** для одного конкретного правила `efes`, прив’язуючись до власної директорії через `import.meta.dirname`.
+## Поведінка
 
-Така архітектура — стандартна для всіх правил із сімейства `npm/rules/<id>/fix.mjs`: одне правило = одна директорія = один однаковий `fix.mjs`, який відрізняється від сусідів лише розміщенням (`import.meta.dirname` бере шлях до **цієї** директорії правила).
+1. Запуск правила.
+    *   Приймає контекст прогону.
+    *   Виконує застосування JS-занепокоєних.
+    *   Застосовує політику.
+    *   Генерує посилання MDC.
+    *   Повертає результат прогону.
 
-## Експорти / API
+2. Запуск у режимі CLI.
+    *   Виконується при запуску через CLI.
+    *   Виконує повний еквівалент команди `npx @nitra/cursor fix <id>`.
+    *   Повертає код виходу.
 
-| Експорт | Тип                                      | Призначення                                                                                                                     |
-| ------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
-| `run`   | `(ctx?: RuleContext) => Promise<number>` | Library API — викликається CLI-оркестратором `@nitra/cursor` для запуску правила в межах одного спільного прогону над монорепо. |
+## Публічний API
 
-Інших іменованих або дефолтних експортів файл не має. Окрім експорту, файл містить **side-effect блок** (top-level `if (isRunAsCli(...))`), що активується тільки коли файл запущено напряму.
+run — запускає правило: applies → JS-concerns → policy → mdc-refs (через runStandardRule).
+Library mode — викликається CLI orchestration через `import + run`.
 
-### Сигнатура `run`
+## Гарантії поведінки
 
-```js
-export function run(ctx)
-```
-
-- **Параметри**:
-  - `ctx` _(optional)_ — об’єкт типу `RuleContext`, імпортований із `npm/scripts/lib/run-standard-rule.mjs`. Містить розділяємий між правилами стан прогону: зокрема `walkCache` (кеш обходу файлів монорепо), а також іншу контекстну інформацію, передану CLI-оркестратором. Якщо `ctx` не передано (наприклад, при ad-hoc виклику), `runStandardRule` створює власний внутрішній контекст.
-- **Повертає**: `Promise<number>` —
-  - `0` — правило не знайшло порушень (OK);
-  - `1` — є щонайменше одне порушення (fail).
-- **Сторонні ефекти**:
-  - Сам `run` нічого не пише в `stdout`/`stderr` напряму, проте делегована функція `runStandardRule` веде логування прогресу, виводить summary порушень і — за потреби — модифікує файли проєкту (`autofix`).
-  - Може читати файлову систему монорепо (через walk), читати конфіг `@nitra/cursor` та `meta.json` правила.
-  - Не викликає `process.exit` у library mode — exit-код доручений викликаючій стороні.
-
-## Функції
-
-### `run(ctx)`
-
-#### Сигнатура
-
-```js
-/**
- * Запускає правило: applies → JS-concerns → policy → mdc-refs (через runStandardRule).
- * 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)
-}
-```
-
-#### Параметри
-
-| Ім’я  | Тип                                          | Обов’язковий | Опис                                                                                                                                                                                                                             |
-| ----- | -------------------------------------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `ctx` | `RuleContext` (див. `run-standard-rule.mjs`) | ні           | Спільний контекст прогону, який оркестратор `@nitra/cursor` створює один раз для всієї пачки правил. Дозволяє ділити дорогий стан (наприклад, `walkCache` — список відсканованих файлів) між правилами без повторного обходу ФС. |
-
-#### Повертає
-
-`Promise<number>` — `0` або `1`. Семантика — звичайна для UNIX exit codes:
-
-- `0` — все добре, правило `efes` не зафіксувало порушень.
-- `1` — правило знайшло хоча б одне порушення (CI має впасти).
-
-#### Логіка
-
-Функція складається з єдиного рядка — `return runStandardRule(import.meta.dirname, ctx)`. Тобто:
-
-1. Беремо абсолютний шлях директорії, у якій лежить **цей** `fix.mjs` (`import.meta.dirname` дає `.../npm/rules/efes`).
-2. Передаємо цей шлях як перший аргумент у `runStandardRule` — щоб бібліотечна функція знала, **яке саме правило** запускає (звідки читати `meta.json`, `efes.mdc`, `policy/*` тощо).
-3. Передаємо отриманий `ctx` (або `undefined`).
-4. Повертаємо отриману `Promise<number>` — без обгортки, без додаткової обробки.
-
-#### Сторонні ефекти
-
-Усі побічні ефекти зосереджені всередині `runStandardRule` (читання файлів, walk, виконання checks, можливі autofix-записи). Сам `run` лише проксує виклик.
-
-### Top-level CLI-блок (без імені, не функція)
-
-```js
-if (isRunAsCli(import.meta.url)) {
-  // eslint-disable-next-line n/no-process-exit -- standalone entry-point має повертати exit-code для CI/IDE
-  process.exit(await runRuleCli(import.meta.dirname))
-}
-```
-
-#### Поведінка
-
-- Виконується **тільки** коли модуль запущено як CLI-точку входу (`bun npm/rules/efes/fix.mjs` або `node ...`). Перевірка `isRunAsCli(import.meta.url)` порівнює URL модуля з `process.argv[1]` (стандартна ідіома для ESM).
-- Якщо умова виконалась — асинхронно (через `await` на top-level, що дозволяє ESM) викликає `runRuleCli(import.meta.dirname)`, який реалізує **повний CLI-цикл**:
-  - завантаження конфігу `@nitra/cursor`;
-  - застосування whitelist/ignore;
-  - запуск самого правила (через ту саму `runStandardRule` або еквівалентний механізм);
-  - друк summary;
-  - повернення exit-коду.
-- Завершує процес через `process.exit(...)` із отриманим кодом (0 або 1).
-
-#### Чому є коментар `eslint-disable-next-line`
-
-У проєкті заборонено `process.exit` (`n/no-process-exit`, `unicorn/no-process-exit`) — але standalone entry-point **повинен** повертати exit-код, інакше CI не зрозуміє результат. Виключення оформлене явним коментарем із поясненням («standalone entry-point має повертати exit-code для CI/IDE»), щоб лінт не падав.
-
-#### Чому є подвійний кінець рядка / два правила в одному disable
-
-Бо обидва правила (`n/no-process-exit` від `eslint-plugin-n` і `unicorn/no-process-exit` від `eslint-plugin-unicorn`) забороняють те саме незалежно — disable має покривати обидва.
-
-## Залежності
-
-### Внутрішні (з того ж монорепо)
-
-| Шлях                                      | Що імпортується                                    | Призначення                                                                                                                                       |
-| ----------------------------------------- | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `../../scripts/lib/run-rule-cli.mjs`      | `isRunAsCli`, `runRuleCli`                         | `isRunAsCli` — детектор «модуль виконано напряму». `runRuleCli` — повний CLI-обгортка для standalone-режиму (config loading, whitelist, summary). |
-| `../../scripts/lib/run-standard-rule.mjs` | `runStandardRule`, тип `RuleContext` (через JSDoc) | Бібліотечна реалізація стандартного потоку правила: `applies → JS-concerns → policy → mdc-refs`.                                                  |
-
-Шляхи з `../../` ведуть на `npm/scripts/lib/` (бо файл лежить у `npm/rules/efes/`).
-
-### Зовнішні
-
-Жодних `npm`-залежностей файл не імпортує напряму — усі вони транзитивно підвантажуються через `runStandardRule` / `runRuleCli`.
-
-### Файли поруч (через `import.meta.dirname`)
-
-Бібліотечні функції очікують у директорії правила (`npm/rules/efes/`) певні файли — їх імпортує не `fix.mjs` напряму, а саме `runStandardRule`/`runRuleCli`:
-
-- `meta.json` — метадані правила (id, applies, policy hints, тощо);
-- `efes.mdc` — людиночитаний опис правила (Markdown + frontmatter);
-- `policy/` — директорія з policy-чеками правила.
-
-## Потік виконання / Використання
-
-### Сценарій A — виклик з CLI `@nitra/cursor` (library mode)
-
-```text
-$ npx @nitra/cursor fix
-└─ CLI оркестратор будує список правил і прогонить кожне:
-   └─ import('npm/rules/efes/fix.mjs')
-      └─ run(ctx)
-         └─ runStandardRule('.../npm/rules/efes', ctx)
-            ├─ читає meta.json + efes.mdc
-            ├─ застосовує applies-фільтри
-            ├─ запускає JS-concerns (eslint-подібні чеки)
-            ├─ запускає policy/* (специфічні чеки правила)
-            └─ перевіряє mdc-refs (узгодженість документації)
-         └─ повертає 0 / 1
-      └─ оркестратор агрегує exit-коди всіх правил
-```
-
-У цьому сценарії **жодних виходів через `process.exit`** із цього файлу — exit-код повертає оркестратор уже наприкінці всього прогону.
-
-### Сценарій B — прямий запуск файлу (standalone mode)
-
-```text
-$ bun npm/rules/efes/fix.mjs
-
-1. ESM завантажує модуль.
-2. На етапі імпорту виконуються top-level statements.
-3. `isRunAsCli(import.meta.url)` -> true.
-4. `await runRuleCli(import.meta.dirname)`:
-   - повністю емулює `npx @nitra/cursor fix efes`;
-   - завантажує конфіг проєкту, whitelist;
-   - запускає правило;
-   - виводить summary в stdout/stderr.
-5. `process.exit(<code>)` — повертає exit-код shell-у / CI / IDE.
-```
-
-Це зручно для:
-
-- швидкого ad-hoc запуску однієї конкретної перевірки під час дебагу правила;
-- інтеграції в IDE-таски (наприклад, окремі run configurations VSCode/JetBrains);
-- ізольованого прогону в pre-commit hook на одне правило.
-
-### Сценарій C — імпорт із тестів
-
-```js
-import { run } from 'npm/rules/efes/fix.mjs'
-
-const code = await run() // 0 або 1
-```
-
-CLI-блок **не запускається** (бо файл не є entry-point процесу), а `run` доступний як звичайна функція. Це дає змогу писати unit/e2e-тести правила без spawn-у дочірнього процесу.
-
-### Інваріанти / нюанси
-
-- `import.meta.dirname` доступний у Node ≥ 20.11 та Bun. Якщо середовище старіше — потрібен fallback через `path.dirname(fileURLToPath(import.meta.url))`. У монорепо `@nitra/cursor` офіційно підтримується Bun-середовище, тому це не проблема.
-- Top-level `await` працює тільки в ESM (`.mjs`) — саме тому файл має розширення `.mjs`, а не `.js`.
-- Дві ролі файлу (library + standalone) — це усвідомлений патерн «dual entry-point»: ESM-import не запускає CLI-блок, бо `isRunAsCli` повертає `false`.
-- Файл навмисно ідентичний по структурі з усіма іншими `npm/rules/<id>/fix.mjs`. Уся специфіка правила `efes` живе в сусідніх файлах (`meta.json`, `efes.mdc`, `policy/`) — у самому `fix.mjs` нічого правило-специфічного немає, окрім розташування.
-
-## Rebuild Test
-
-Уявно «перебудувавши» файл лише за цією документацією, маємо отримати:
-
-- ESM-модуль `.mjs` із двома імпортами зі спільної бібліотеки `npm/scripts/lib/`:
-  - `{ isRunAsCli, runRuleCli }` із `../../scripts/lib/run-rule-cli.mjs`;
-  - `{ runStandardRule }` із `../../scripts/lib/run-standard-rule.mjs`.
-- Один іменований експорт `run(ctx)` із JSDoc, що описує параметр `ctx` як `RuleContext` (тип взято через `import('...')` JSDoc-нотацію) і повертає `Promise<number>` (`0` — OK, `1` — порушення). Тіло — один рядок `return runStandardRule(import.meta.dirname, ctx)`.
-- Top-level guard `if (isRunAsCli(import.meta.url)) { process.exit(await runRuleCli(import.meta.dirname)) }` із коментарем-disable для двох ESLint-правил (`n/no-process-exit`, `unicorn/no-process-exit`) і поясненням «standalone entry-point має повертати exit-code для CI/IDE».
-- Жодних інших declarations, експортів чи побічних ефектів.
-
-Такий «реконструйований» файл функціонально й текстово збігається з оригіналом `npm/rules/efes/fix.mjs`.
+- Read-only: файл не виконує операцій запису у файлову систему.
+- Кешує результати в межах одного прогону.
+- Не звертається до мережі.

package/rules/feedback/docs/fix.md

@@ -1,7 +1,7 @@
 ---
 docgen:
   source: npm/rules/feedback/fix.mjs
-  crc: 12fc1644
+  crc: 38cf876b
   score: 100
 ---
 
@@ -9,19 +9,21 @@ docgen:
 
 ## Огляд
 
-Модуль виконує задану перевірку, ініціалізуючи її з локального файлу конфігурації. При запуску як окрема програма, він завантажує конфігурацію, перевіряє білий список та надає звіт про результати виконання. Результат виконання правила повертається як код виходу.
+Виконує обробку JS-занепокоєних на наданому контексті прогону. Застосовує визначену політику та генерує посилання MDC. Повертає результат прогону.
 
 ## Поведінка
 
-1. Викликається функція `run` для виконання правила.
-2. Виконання правила відбувається шляхом ініціалізації стандартного правила з директорії цього файлу.
-3. Якщо код виконується як окрема утиліта (standalone), ініціюється повний запуск правила.
-4. Запуск правила як окремої утиліти включає завантаження конфігурації, перевірку білого списку та підведення підсумків.
-5. Результат цього запуску повертається як код виходу.
+1. Запуск правила.
+    *   Приймає контекст прогону.
+    *   Виконує застосування JS-занепокоєних.
+    *   Застосовує політику.
+    *   Генерує посилання MDC.
+    *   Повертає результат прогону.
 
 ## Публічний API
 
-run — виконує послідовність перевірок: застосовує правила, аналізує JS-занепокоєння, порівнює з політикою та перевіряє посилання MDC.
+run — запускає правило: applies → JS-concerns → policy → mdc-refs (через runStandardRule).
+Library mode — викликається CLI orchestration через `import + run`.
 
 ## Гарантії поведінки
 

package/rules/ga/docs/fix.md

@@ -1,7 +1,7 @@
 ---
 docgen:
   source: npm/rules/ga/fix.mjs
-  crc: 12fc1644
+  crc: 38cf876b
   score: 100
 ---
 
@@ -9,16 +9,21 @@ docgen:
 
 ## Огляд
 
-Модуль відповідає за запуск механізму виконання стандартного правила. Він шукає та застосовує правила, використовуючи поточний каталог як джерело. При запуску як окрема програма, він ініціює виконання команди, необхідної для застосування цього правила.
+Виконує обробку JS-занепокоєних на наданому контексті прогону. Застосовує визначену політику та генерує посилання MDC. Повертає результат прогону.
 
 ## Поведінка
 
-1. Викликає механізм виконання стандартного правила, використовуючи поточний каталог як джерело правил.
-2. Якщо скрипт виконується як окрема програма, запускає оркестрацію командного рядка для виконання правила.
+1. Запуск правила.
+    *   Приймає контекст прогону.
+    *   Виконує застосування JS-занепокоєних.
+    *   Застосовує політику.
+    *   Генерує посилання MDC.
+    *   Повертає результат прогону.
 
 ## Публічний API
 
-run — виконує послідовність дій: застосовує правила, обробляє JS-занепокоєння, перевіряє політику та посилання MDC.
+run — запускає правило: applies → JS-concerns → policy → mdc-refs (через runStandardRule).
+Library mode — викликається CLI orchestration через `import + run`.
 
 ## Гарантії поведінки