@nitra/cursor 5.3.4 → 6.0.0

package/rules/text/js/docs/lint.md

@@ -1,122 +1,25 @@
+---
+docgen:
+  source: npm/rules/text/js/lint.mjs
+  crc: 49aab7ce
+  score: 100
+---
+
 # lint.mjs
 
 ## Огляд
 
-Модуль `lint.mjs` — це тонкий адаптер-обгортка, що реалізує CI-крок (контракт `lint(files)`) для правила `text` у складі n-cursor правил репозиторію. Його єдина роль — делегувати виконання у внутрішній CLI правила `text`, який знаходиться поряд у директорії `../lint/lint.mjs`.
-
-Особливості модуля:
-
-- Працює в режимі **whole-repo**: незалежно від того, які файли передає викликаюча сторона (наприклад, обгортка `lint-js` чи CI-оркестратор), аналіз виконується по всьому репозиторію цілком.
-- Per-file режиму **немає**: вхідний параметр `files` навмисно ігнорується (підкреслено префіксом `_` у назві аргумента).
-- Повертає числовий exit code (Promise), сумісний з конвенцією Unix-процесів: `0` — успіх, ненульовий — помилки лінту.
-- Модуль не містить власної логіки перевірки тексту: вся реальна робота (запуск пов’язаних інструментів типу `dotenv-linter`, `shellcheck`, `v8r` тощо) — у `../lint/lint.mjs`.
-
-Файл написаний у форматі **ES Modules** (`.mjs`) з JSDoc-анотаціями для статичної типізації без TypeScript-компіляції.
-
-## Експорти / API
-
-| Експорт | Тип                                                    | Призначення                                                            |
-| ------- | ------------------------------------------------------ | ---------------------------------------------------------------------- |
-| `lint`  | `async function (files?: string[]) => Promise<number>` | CI-крок-делегат у `runLintTextCli`. Іменований експорт (named export). |
-
-Default-експорту немає. Сторонніх ефектів на рівні модуля (top-level side effects) також немає — лише імпорт залежності.
-
-### Сигнатура
-
-```js
-export async function lint(_files): Promise<number>
-```
-
-### Контракт CI-кроку
-
-Модуль реалізує загальний інтерфейс CI-крока правил n-cursor:
-
-- Назва експорту: `lint`.
-- Сигнатура приймає опціональний `files: string[] | undefined`.
-- Повертає `Promise<number>` — exit code.
-- Не кидає винятків у нормальному сценарії; помилки сигналізуються через ненульовий exit code, який повертає делегат `runLintTextCli`.
-
-## Функції
-
-### `lint(_files)`
-
-**Сигнатура:** `async function lint(_files: string[] | undefined): Promise<number>`
-
-**Параметри:**
-
-| Ім’я     | Тип                     | Опис                                                                                                                                                                                                                                                        |
-| -------- | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `_files` | `string[] \| undefined` | Список файлів, які теоретично потрібно перевірити. **Ігнорується** — правило `text` працює у whole-repo режимі. Префікс `_` у назві аргументу — конвенція, що позначає невикористаний параметр (зокрема, щоб ESLint/lint-правила не лаялись на unused arg). |
-
-**Повертає:** `Promise<number>` — exit code, отриманий від виклику `runLintTextCli()`. Зазвичай `0` означає, що всі перевірки пройшли успішно, а будь-яке інше число — що знайдено порушення або сталася помилка інструмента.
-
-**Side effects:** Сам по собі `lint` додаткових ефектів не вносить. Усі побічні ефекти (запис у stdout/stderr, читання файлів, запуск зовнішніх процесів) виконуються всередині `runLintTextCli()`, на який делегується виклик.
-
-**Поведінка:**
-
-1. Викликає `runLintTextCli()` без аргументів.
-2. Повертає результат як є (через `await` неявно через `return await`-форму — `async`-функція автоматично «розгортає» Promise з тіла).
-
-Логіки трансформації параметрів, фільтрації, перевірки прапорців тощо — немає. Це навмисно мінімалістична функція-адаптер.
-
-## Залежності
-
-### Імпорти
-
-| Що               | Звідки             | Призначення                                                                                                                                                                                                       |
-| ---------------- | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `runLintTextCli` | `../lint/lint.mjs` | Запускає реальний CLI-обробник правила `text`. Саме він агрегує запуски під-інструментів (наприклад, `run-dotenv-linter.mjs`, `run-shellcheck.mjs`, `run-v8r.mjs`, які лежать у тій самій директорії `../lint/`). |
-
-### Зовнішні (npm) залежності
-
-Прямих імпортів з npm у файлі немає. Усі npm-залежності (якщо такі є) приховані у транзитивній залежності — `../lint/lint.mjs`.
-
-### Структурний контекст
-
-Файл лежить у `npm/rules/text/js/lint.mjs`. У тій самій директорії розташовані інші CI-крокові модулі правила `text` (наприклад, `formatting.mjs`, `forbidden-prettier.mjs`). Усі вони — однотипні делегати, що реалізують контракт CI-крока.
-
-Бенефіціар:
-
-- `../lint/lint.mjs` — справжній CLI правила `text`, що містить runner-логіку (parsing аргументів, оркестрація під-інструментів, формування звіту, exit code).
-
-## Потік виконання / Використання
-
-### Сценарій 1: виклик через CI-оркестратор правил
-
-1. Оркестратор правил (наприклад, агрегований раннер у `lint-js` чи кореневий `bun run lint`) виявляє правило `text` і знаходить його CI-кроки в `npm/rules/text/js/*.mjs`.
-2. Для кожного CI-крока (зокрема `lint.mjs`) оркестратор імпортує named export `lint`.
-3. Викликає `await lint(filesArrayOrUndefined)`.
-4. Адаптер ігнорує `files`, делегує виклик у `runLintTextCli()`.
-5. Реальний CLI робить whole-repo аналіз: запускає `dotenv-linter`, `shellcheck`, `v8r` тощо (відповідно до того, що оголошено в `../lint/lint.mjs`).
-6. Повертає exit code.
-7. Оркестратор агрегує exit code-и всіх CI-кроків і приймає рішення про загальний успіх/невдачу.
-
-### Сценарій 2: пряме виконання з коду
-
-```js
-import { lint } from 'npm/rules/text/js/lint.mjs'
-
-const code = await lint()
-process.exit(code)
-```
-
-Передача аргументу `files` нічого не змінює (буде проігнорована):
-
-```js
-const code = await lint(['some/file.txt']) // _files ігнорується
-```
-
-### Чому per-file немає
-
-Правило `text` за своєю природою сканує весь репозиторій (наприклад, перевіряє `.env`-файли, shell-скрипти, JSON Schema-файли через v8r). Для нього передача обмеженого списку файлів від CI не має сенсу — обробляти треба весь робочий простір. Звідси й whole-repo режим, явно зафіксований у JSDoc-коментарі та підкреслений підкресленням у назві параметра.
+Файл надає функцію lint, яка делегує завдання CLI правилам. Функція не підтримує режим per-file, і параметр files ігнорується. Функція повертає Promise з кодом виходу.
 
-### Очікувані коди виходу
+## Поведінка
 
-| Code  | Значення                                                                                            |
-| ----- | --------------------------------------------------------------------------------------------------- |
-| `0`   | Усі під-перевірки правила `text` пройшли успішно.                                                   |
-| ≠ `0` | Знайдено порушення або помилка одного з інструментів. Конкретний код визначається `runLintTextCli`. |
+1. Викликається функція lint з аргументом files.
+2. Функція lint делегує виконання у CLI правила.
+3. Режим per-file не підтримується.
+4. Параметр files ігнорується.
+5. Функція повертає Promise з кодом виходу.
 
-### Обробка помилок
+## Гарантії поведінки
 
-Адаптер не містить `try/catch`. Якщо `runLintTextCli` кине виняток (нештатна ситуація), він пробулькується нагору — до викликаючого. Це навмисний дизайн: оркестратор сам вирішує, як трактувати unhandled rejection.
+- Read-only: файл не виконує операцій запису у файлову систему.
+- Не звертається до мережі.

package/rules/text/js/lint.mjs

@@ -1,12 +1,14 @@
 /**
- * Ci-крок text: делегує у наявний CLI правила (per-file режиму немає — `files` ігнорується).
+ * Крок text: делегує у наявний CLI правила (per-file режиму немає — `files` ігнорується).
  */
 import { runLintTextCli } from '../lint/lint.mjs'
 
 /**
  * @param {string[] | undefined} _files ігнорується (whole-repo аналіз)
+ * @param {string} [_cwd] корінь (ігнорується — CLI працює від process.cwd())
+ * @param {{ readOnly?: boolean }} [opts] readOnly → детект без авто-фіксу (нуль мутацій)
  * @returns {Promise<number>} exit code
  */
-export function lint(_files) {
-  return runLintTextCli()
+export function lint(_files, _cwd, opts = {}) {
+  return runLintTextCli({ readOnly: opts.readOnly === true })
 }

package/rules/text/lint/docs/lint.md

@@ -1,7 +1,7 @@
 ---
 docgen:
   source: npm/rules/text/lint/lint.mjs
-  crc: 05f3f108
+  crc: bdaef0f8
 ---
 
 # `lint.mjs` — CLI-обгортка `lint-text`

package/rules/text/lint/docs/run-dotenv-linter.md

@@ -1,7 +1,7 @@
 ---
 docgen:
   source: npm/rules/text/lint/run-dotenv-linter.mjs
-  crc: 8bb94af4
+  crc: 4719ac66
 ---
 
 # run-dotenv-linter.mjs

package/rules/text/lint/docs/run-shellcheck.md

@@ -1,7 +1,7 @@
 ---
 docgen:
   source: npm/rules/text/lint/run-shellcheck.mjs
-  crc: e6fa8c23
+  crc: 6b2daaa8
 ---
 
 # run-shellcheck.mjs

package/rules/text/lint/lint.mjs

@@ -95,28 +95,30 @@ function preflight(dep) {
 
 /**
  * Внутрішні кроки `lint-text` без локу.
+ * @param {boolean} [readOnly] true → лише детект без авто-фіксу (нуль мутацій — CI/pre-commit)
  * @returns {number} 0 — все OK, інакше — код першого кроку, що впав
  */
-function runLintTextSteps() {
+function runLintTextSteps(readOnly = false) {
   // Auto-install: throws on failure → propagates as exit 1 from runStandardLint
   ensureTool('shellcheck')
   ensureTool('dotenv-linter')
 
-  // patch is hint-only (system tool)
-  if (!preflight(PATCH_PREFLIGHT)) return 1
+  // patch потрібен лише для авто-фіксу shellcheck; у read-only пропускаємо preflight.
+  if (!readOnly && !preflight(PATCH_PREFLIGHT)) return 1
 
   const cspellCode = runLintStep('cspell', 'npx', ['cspell', '.'])
   if (cspellCode !== 0) return cspellCode
 
-  console.log('\n▶ shellcheck (авто-фікс + фінальна перевірка *.sh)')
-  const shellcheckCode = runShellcheckText()
+  console.log(`\n▶ shellcheck (${readOnly ? 'перевірка' : 'авто-фікс + фінальна перевірка'} *.sh)`)
+  const shellcheckCode = runShellcheckText(process.cwd(), readOnly)
   if (shellcheckCode !== 0) return shellcheckCode
 
-  console.log('\n▶ dotenv-linter (авто-фікс + фінальна перевірка .env*)')
-  const dotenvCode = runDotenvLinter()
+  console.log(`\n▶ dotenv-linter (${readOnly ? 'перевірка' : 'авто-фікс + фінальна перевірка'} .env*)`)
+  const dotenvCode = runDotenvLinter(process.cwd(), readOnly)
   if (dotenvCode !== 0) return dotenvCode
 
-  const markdownlintCode = runLintStep('markdownlint', 'bunx', ['markdownlint-cli2', '--fix', '**/*.md', '**/*.mdc'])
+  const mdArgs = readOnly ? ['markdownlint-cli2', '**/*.md', '**/*.mdc'] : ['markdownlint-cli2', '--fix', '**/*.md', '**/*.mdc']
+  const markdownlintCode = runLintStep('markdownlint', 'bunx', mdArgs)
   if (markdownlintCode !== 0) return markdownlintCode
 
   console.log('\n▶ v8r (schema-валідація json/json5/yaml/yml/toml)')
@@ -125,6 +127,8 @@ function runLintTextSteps() {
 
 /**
  * Публічна CLI-форма: серіалізує через `withLock('lint-text')` + дедуп за станом git-дерева.
+ * @param {{ readOnly?: boolean }} [opts] readOnly → детект без авто-фіксу
  * @returns {Promise<number>} код виходу
  */
-export const runLintTextCli = () => runStandardLint(import.meta.dirname, () => runLintTextSteps())
+export const runLintTextCli = (opts = {}) =>
+  runStandardLint(import.meta.dirname, () => runLintTextSteps(opts.readOnly === true))

package/rules/text/lint/run-dotenv-linter.mjs

@@ -52,9 +52,10 @@ function buildExcludeArgs() {
 /**
  * Запускає dotenv-linter з авто-фіксом і фінальною перевіркою.
  * @param {string} [cwd] робочий каталог (за замовчуванням `process.cwd()`)
+ * @param {boolean} [readOnly] true → пропустити авто-фікс (`fix`), лише `check` (нуль мутацій)
  * @returns {number} 0 — OK; 1 — інструмент відсутній або є залишкові порушення
  */
-export function runDotenvLinter(cwd = process.cwd()) {
+export function runDotenvLinter(cwd = process.cwd(), readOnly = false) {
   const root = resolve(cwd)
   const bin = resolveCmd('dotenv-linter')
   if (!bin) {
@@ -63,15 +64,17 @@ export function runDotenvLinter(cwd = process.cwd()) {
   }
 
   const exclude = buildExcludeArgs()
-  const fixRun = spawnSync(bin, ['fix', '-r', '--no-backup', '--quiet', ...exclude, '.'], {
-    cwd: root,
-    encoding: 'utf8',
-    env: process.env,
-    stdio: ['ignore', 'pipe', 'pipe']
-  })
-  if (fixRun.error) {
-    process.stderr.write(`${fixRun.error.message}\n`)
-    return 1
+  if (!readOnly) {
+    const fixRun = spawnSync(bin, ['fix', '-r', '--no-backup', '--quiet', ...exclude, '.'], {
+      cwd: root,
+      encoding: 'utf8',
+      env: process.env,
+      stdio: ['ignore', 'pipe', 'pipe']
+    })
+    if (fixRun.error) {
+      process.stderr.write(`${fixRun.error.message}\n`)
+      return 1
+    }
   }
 
   const checkRun = spawnSync(bin, ['check', '-r', '--quiet', ...exclude, '.'], {

package/rules/text/lint/run-shellcheck.mjs

@@ -96,17 +96,19 @@ export function listShellScriptPaths(cwd) {
 /**
  * Запускає shellcheck із авто-виправленнями і фінальною перевіркою.
  * @param {string} [cwd] робочий каталог (за замовчуванням `process.cwd()`)
+ * @param {boolean} [readOnly] true → пропустити авто-фікс (diff+patch), лише фінальна перевірка
  * @returns {number} 0 — OK; 1 — помилка середовища або залишкові зауваження shellcheck
  */
-export function runShellcheckText(cwd = process.cwd()) {
+export function runShellcheckText(cwd = process.cwd(), readOnly = false) {
   const root = resolve(cwd)
   const shellcheck = resolveCmd('shellcheck')
   if (!shellcheck) {
     printShellcheckInstallHints()
     return 1
   }
-  const patchBin = resolveCmd('patch')
-  if (!patchBin) {
+  // patch потрібен лише для авто-фіксу (diff+patch); у read-only його відсутність не блокує детект.
+  const patchBin = readOnly ? null : resolveCmd('patch')
+  if (!readOnly && !patchBin) {
     printPatchInstallHints()
     return 1
   }
@@ -116,9 +118,11 @@ export function runShellcheckText(cwd = process.cwd()) {
     return 0
   }
 
-  for (const rel of files) {
-    const fixCode = autofixOneFile(shellcheck, patchBin, root, rel)
-    if (fixCode !== 0) return fixCode
+  if (!readOnly) {
+    for (const rel of files) {
+      const fixCode = autofixOneFile(shellcheck, /** @type {string} */ (patchBin), root, rel)
+      if (fixCode !== 0) return fixCode
+    }
   }
 
   return runFinalShellcheck(shellcheck, files, root)

package/rules/text/meta.json

@@ -1 +1 @@
-{ "auto": "завжди", "lint": "ci" }
+{ "auto": "завжди", "lint": "per-file" }

package/rules/vue/docs/fix.md

@@ -1,127 +1,34 @@
-# fix.mjs — entry-point правила `vue`
+---
+docgen:
+  source: npm/rules/vue/fix.mjs
+  crc: 38cf876b
+  score: 90
+---
 
-## Огляд
-
-Файл `npm/rules/vue/fix.mjs` — це **точка входу** (entry-point) для правила `vue` у системі `@nitra/cursor`. Файл одночасно виконує дві ролі:
-
-1. **Library mode** — експортує функцію `run(ctx)`, яку викликає зовнішній оркестратор (CLI `@nitra/cursor`, інші правила, тести) з підготовленим контекстом прогону.
-2. **Standalone mode** — якщо файл запущено напряму (наприклад, `bun npm/rules/vue/fix.mjs`), він самостійно піднімає повноцінний CLI-цикл, еквівалентний `npx @nitra/cursor fix vue`.
-
-Сам файл не містить специфічної для Vue логіки правил. Уся логіка делегується у спільні бібліотеки `runStandardRule` (виконання стандартних фаз правила) і `runRuleCli` (підготовка CLI-середовища). Завдяки цьому `fix.mjs` у директорії правила `vue` залишається тонким shim-файлом, який лише підставляє свою директорію як ідентифікатор правила.
-
-Стандартний пайплайн, який під цим запускається (через `runStandardRule`), складається з фаз:
-
-- `applies` — детекція файлів/області застосування правила,
-- `JS-concerns` — перевірки JS/JSX/TS-аспектів коду,
-- `policy` — застосування policy-чеків (warn/error),
-- `mdc-refs` — узгодженість MDC-документації та посилань.
-
-## Експорти / API
-
-| Назва | Тип        | Опис                                                                                            |
-| ----- | ---------- | ----------------------------------------------------------------------------------------------- |
-| `run` | `function` | Named export. Library-точка входу правила. Приймає опційний `ctx` і повертає `Promise<number>`. |
-
-**Side-effect експорт:** при виконанні модуля під CLI (умова `isRunAsCli(import.meta.url)`) модуль вмикає standalone-режим і завершує процес викликом `process.exit(...)` з exit-кодом, отриманим від `runRuleCli`. Цей побічний ефект виконується на верхньому рівні модуля (top-level `await`), тому імпорт файлу як ESM-модуля з іншого файлу **не** активує standalone-гілку — її активує лише пряме виконання інтерпретатором.
-
-## Функції
-
-### `run(ctx)`
-
-Library-функція правила. Делегує виконання у спільну реалізацію `runStandardRule`, передаючи їй власну директорію модуля (`import.meta.dirname`) як ідентифікатор правила та переданий контекст.
-
-- **Сигнатура:** `function run(ctx): Promise<number>`
-- **Параметри:**
-  - `ctx` _(optional)_ — об'єкт типу `RuleContext` із модуля `../../scripts/lib/run-standard-rule.mjs`. У ньому, серед іншого, передається `walkCache` для уникнення повторного обходу файлової системи між послідовно запущеними правилами. Якщо `ctx` не передано, `runStandardRule` створює його самостійно.
-- **Повертає:** `Promise<number>` — exit-код прогону правила:
-  - `0` — порушень немає (OK);
-  - `1` — знайдено порушення (rule violations).
-- **Side effects:** усі побічні ефекти ховаються всередині `runStandardRule` (читання файлів проєкту, можливі автоматичні фікси, виведення summary в stdout/stderr). Сам `run` додаткових side-effects не має, поза тим, що значення повернення завжди є `Promise`, навіть якщо `runStandardRule` поверне синхронно — це гарантує контракт async-pipeline для оркестратора.
-- **Помилки:** функція не обгортає виняткові ситуації — будь-яка помилка з `runStandardRule` пробрасується нагору (rejection промісу) і має оброблятись на рівні CLI/орхестратора.
-
-### Top-level standalone-блок
-
-Не функція, а top-level гілка модуля:
-
-```js
-if (isRunAsCli(import.meta.url)) {
-  process.exit(await runRuleCli(import.meta.dirname))
-}
-```
+# fix.mjs
 
-- **Семантика:** `isRunAsCli(import.meta.url)` повертає `true`, коли поточний модуль є entry-point процесу (тобто Node/Bun запустив саме цей файл, а не імпортував його). У такому разі викликається `runRuleCli` з директорією поточного правила; її exit-код передається у `process.exit(...)`, щоб CI/IDE отримали коректний статус.
-- **Side effects:**
-  - синхронне завершення процесу через `process.exit`;
-  - усе, що робить `runRuleCli` (завантаження конфігу, whitelist, summary).
-- **ESLint-винятки:** standalone-entry-point має право робити `process.exit`, тому над цим викликом стоять директиви `// eslint-disable-next-line n/no-process-exit, unicorn/no-process-exit`. Це штатна практика для двороле́вих fix.mjs.
-
-## Залежності
-
-Імпорти модуля:
-
-- `isRunAsCli` — з `../../scripts/lib/run-rule-cli.mjs`. Утиліта-детектор: чи поточний модуль є entry-point (CLI mode), чи його імпортнули як бібліотеку.
-- `runRuleCli` — з `../../scripts/lib/run-rule-cli.mjs`. Виконує повну CLI-оркестрацію для одного правила: завантажує конфіг, формує whitelist, друкує summary та повертає exit-код. Використовується тільки у standalone-гілці.
-- `runStandardRule` — з `../../scripts/lib/run-standard-rule.mjs`. Виконує стандартний пайплайн правила: `applies → JS-concerns → policy → mdc-refs`. JSDoc-типи `RuleContext` теж приходять із цього модуля (через `@param`-import).
-
-Неявні залежності:
-
-- Структура директорії правила (`npm/rules/vue/`) має містити очікувані `runStandardRule` під-директорії/файли: `js/`, `lib/`, `policy/`, `meta.json`, `vue.mdc` тощо. Сам `fix.mjs` не звертається до них напряму — він лише підставляє свій `import.meta.dirname`, а решту виявляє shared-runner.
-- ESM-середовище (Node.js ≥ 20 / Bun) з підтримкою `import.meta.url` та `import.meta.dirname`.
-
-## Потік виконання / Використання
-
-### Library mode (виклик з оркестратора)
-
-```js
-import { run } from './npm/rules/vue/fix.mjs'
-
-const exitCode = await run(ctx) // ctx — спільний RuleContext із walkCache
-if (exitCode !== 0) {
-  // у правилі vue знайдено порушення → обробляємо
-}
-```
-
-Послідовність:
-
-1. Оркестратор імпортує `fix.mjs`. Гілка `if (isRunAsCli(...))` не виконується, бо `import.meta.url` не є entry-point.
-2. Оркестратор викликає `run(ctx)`.
-3. `run` передає `import.meta.dirname` (= `…/npm/rules/vue`) і `ctx` у `runStandardRule`.
-4. `runStandardRule` виконує фази `applies → JS-concerns → policy → mdc-refs` для правила `vue`, використовуючи кеші з `ctx` (наприклад, `walkCache`).
-5. Повертається exit-код (`0` або `1`), який оркестратор інтегрує у свій агрегований підсумок.
-
-### Standalone mode (пряме виконання)
-
-```bash
-bun npm/rules/vue/fix.mjs
-# або
-node npm/rules/vue/fix.mjs
-```
-
-Послідовність:
-
-1. Інтерпретатор завантажує модуль; виконуються імпорти.
-2. Виконується top-level код: `isRunAsCli(import.meta.url)` повертає `true`.
-3. Викликається `await runRuleCli(import.meta.dirname)` — це повний еквівалент `npx @nitra/cursor fix vue`:
-   - читає конфіг,
-   - застосовує whitelist,
-   - усередині піднімає той самий `runStandardRule`-цикл (або сумісний з ним),
-   - друкує summary.
-4. Отриманий exit-код передається у `process.exit(...)`, процес завершується з відповідним кодом для CI/IDE.
+## Огляд
 
-### Чому існують дві ролі
+Файл застосовує правило `runStandardRule` до наданого контексту прогону через функцію `runStandardRule` і повертає отриманий результат. У режимі CLI він виконує команду `npx @nitra/cursor fix <id>` та визначає вихідний код процесу на основі отриманого результату.
 
-Подвійна реалізація (`run` + standalone) дозволяє:
+## Поведінка
 
-- викликати правило **разом з іншими** з єдиного оркестратора без зайвого spawn-у процесів і без втрати спільних кешів (бібліотечний шлях);
-- запускати правило **окремо** з командного рядка під час локальної розробки/дебагу, маючи повноцінний CLI-вивід (standalone-шлях).
+1. Запуск правила.
+    *   Приймає контекст прогону.
+    *   Використовує runStandardRule для застосування політики.
+    *   Повертає результат прогону.
+2. Запуск у режимі CLI.
+    *   Викликається через `import + run`.
+    *   Виконує повний еквівалент `npx @nitra/cursor fix <id>`.
+    *   Визначає вихідний код процесу на основі результату.
 
-## Rebuild Test
+## Публічний API
 
-Можна повністю відтворити поведінку цього файлу з опису вище:
+run — запускає правило: applies → JS-concerns → policy → mdc-refs (через runStandardRule).
+Library mode — викликається CLI orchestration через `import + run`.
 
-- Імпортуються тільки два символи з двох сусідніх бібліотек: `isRunAsCli`, `runRuleCli` з `../../scripts/lib/run-rule-cli.mjs` та `runStandardRule` з `../../scripts/lib/run-standard-rule.mjs`.
-- Експортується одна named-функція `run(ctx)`, яка повертає результат `runStandardRule(import.meta.dirname, ctx)` — отже, є async (повертає `Promise<number>`).
-- На рівні модуля стоїть умова `if (isRunAsCli(import.meta.url)) { process.exit(await runRuleCli(import.meta.dirname)) }` з відповідними ESLint-disable-коментарями для `n/no-process-exit` та `unicorn/no-process-exit`.
-- Жодних додаткових іменованих експортів, default-експортів, констант чи побічних викликів у файлі немає.
+## Гарантії поведінки
 
-Цього достатньо, щоб переписати файл байт-у-байт еквівалентно (з точністю до коментарів/форматування), не звертаючись до оригіналу.
+- Read-only: файл не виконує операцій запису у файлову систему.
+- Кешує результати в межах одного прогону.
+- Не звертається до мережі.