@nitra/cursor 3.21.1 → 3.23.0

package/rules/ci4/docs/fix.md

@@ -0,0 +1,179 @@
+# fix.mjs — точка входу правила `ci4` (library + standalone CLI)
+
+## Огляд
+
+Файл `npm/rules/ci4/fix.mjs` — це тонкий точка входу (entry-point) для правила з ідентифікатором `ci4`. Він не містить власної прикладної логіки перевірки/виправлення: уся робота делегується утиліті `runStandardRule`, яка реалізує стандартний послідовний конвеєр прогону правила:
+
+1. `applies` — перевірка, чи правило взагалі застосовне до поточного робочого дерева/конфігурації;
+2. `JS-concerns` — перевірки/виправлення, специфічні для JS/TS-аспектів правила;
+3. `policy` — політики (declarative rules), які описують стан, що має бути дотриманий;
+4. `mdc-refs` — перевірка відповідності правила супровідній `.mdc`-документації (посилання та узгодженість).
+
+Файл одночасно виконує дві ролі:
+
+- **library mode** — інші модулі (зокрема CLI-оркестратор `@nitra/cursor`) імпортують named-export `run(ctx)` і викликають його з готовим контекстом (наприклад, із `walkCache`, щоб не повторювати обхід дерева між правилами);
+- **standalone mode** — файл можна запустити напряму через `bun rules/ci4/fix.mjs`. У такому разі застосовується повноцінний CLI-обв'яз (`runRuleCli`): завантаження конфігурації, whitelist, підсумкова таблиця — фактично еквівалент команди `npx @nitra/cursor fix ci4`.
+
+Сам файл містить лише делегування й сторожовий блок для standalone-запуску, тому всі побічні ефекти (виведення в stdout, читання конфігів, мутації файлів проекту) ховаються всередині `runStandardRule` та `runRuleCli`.
+
+## Експорти / API
+
+| Експорт | Тип                                               | Призначення                                                                      |
+| ------- | ------------------------------------------------- | -------------------------------------------------------------------------------- |
+| `run`   | named export, функція `(ctx?) => Promise<number>` | Library-entry для виклику правила `ci4` з оркестратора. Повертає exit-код (0/1). |
+
+Default export відсутній. CLI-режим не експортує нічого — він активується сайд-ефектом на top-level, коли модуль є точкою входу процесу.
+
+## Функції
+
+### `run(ctx)`
+
+**Сигнатура.**
+
+```js
+export function run(ctx)
+```
+
+**Параметри.**
+
+- `ctx` — `RuleContext` (опціональний). Тип посилається на `import('../../scripts/lib/run-standard-rule.mjs').RuleContext`. Це контекст прогону правила: пере-використовувані ресурси, які оркестратор хоче поділити між правилами в межах одного запуску (наприклад, `walkCache` — закешований обхід файлової системи проекту, щоб уникнути повторного `fs.readdir`).
+- Параметр опціональний: якщо `ctx` не передано, `runStandardRule` створить/працюватиме без зовнішнього кешу.
+
+**Повертає.**
+
+- `Promise<number>` — exit-код прогону правила:
+  - `0` — правило не знайшло порушень або всі порушення були автоматично виправлені;
+  - `1` — є порушення, які залишилися після спроби виправлення (тобто правило вважається проваленим).
+
+**Що робить.**
+
+- Викликає `runStandardRule(import.meta.dirname, ctx)`. Перший аргумент `import.meta.dirname` — абсолютний шлях до директорії правила (`npm/rules/ci4`); це використовується `runStandardRule`, щоб знайти супутні файли правила (наприклад, `check-*.mjs`, `mdc`-документацію, ID правила тощо).
+- Усі реальні дії (обхід проекту, читання/запис файлів, друк summary) виконуються всередині `runStandardRule` — у самому `run` побічних ефектів немає.
+
+**Side effects.**
+
+- Безпосередньо в коді функції — немає. Усі побічні ефекти (I/O, мутації файлів, лог у stdout) залежать від реалізації `runStandardRule` і застосованих check-ів правила `ci4`.
+
+### Top-level standalone-блок (без імені)
+
+**Сигнатура (умовно).**
+
+```js
+if (isRunAsCli(import.meta.url)) {
+  process.exit(await runRuleCli(import.meta.dirname))
+}
+```
+
+**Що робить.**
+
+- `isRunAsCli(import.meta.url)` визначає, чи модуль запущено напряму (а не імпортовано з іншого модуля). Реалізація — у `npm/scripts/lib/run-rule-cli.mjs`.
+- Якщо так — викликає `runRuleCli(import.meta.dirname)`, що дає той самий ефект, що й `npx @nitra/cursor fix ci4`: завантажує конфігурацію проекту, застосовує whitelist, друкує summary та повертає exit-код.
+- Результат передається в `process.exit(...)` — щоб CI/IDE отримали коректний код завершення.
+
+**Параметри / повертає.**
+
+- Не функція як така — це топ-рівневий `await` із умовою. Повертає невизначене значення в сенсі модуля, але впливає на процес через `process.exit`.
+
+**Side effects.**
+
+- Завершує Node/Bun-процес із кодом, який повернув `runRuleCli`.
+- Випуск `console.log`/`console.error` усередині `runRuleCli` (за реалізацією).
+- Можливі мутації файлів проекту, якщо правило підтримує auto-fix.
+
+**Лінт-винятки в коді.**
+
+- Рядок із `process.exit` вимкнено для двох правил ESLint:
+  - `n/no-process-exit` (плагін `eslint-plugin-n`) — забороняє прямий виклик `process.exit` у бібліотечному коді;
+  - `unicorn/no-process-exit` (плагін `eslint-plugin-unicorn`) — те саме застереження.
+- Причина (вказана в коментарі): standalone entry-point має повертати exit-code для CI/IDE — без `process.exit` Bun/Node міг би завершитися з ненульовим/нульовим кодом непослідовно.
+
+## Залежності
+
+### Внутрішні (відносні імпорти)
+
+- `../../scripts/lib/run-rule-cli.mjs`
+  - `isRunAsCli(importMetaUrl)` — детектор «модуль запущено напряму»;
+  - `runRuleCli(ruleDir)` — повний CLI-обв'яз для одного правила (config + whitelist + summary).
+- `../../scripts/lib/run-standard-rule.mjs`
+  - `runStandardRule(ruleDir, ctx?)` — стандартна послідовність `applies → JS-concerns → policy → mdc-refs`;
+  - JSDoc-тип `RuleContext` — структура контексту, який передається в `run`.
+
+### Зовнішні
+
+- Прямих зовнішніх npm-залежностей немає. Усі залежності — внутрішні модулі пакета `@nitra/cursor` (`npm/scripts/lib/...`).
+
+### Платформа
+
+- Очікується середовище Node.js/Bun з підтримкою:
+  - ESM-модулів (`import`/`export`, `import.meta.dirname`, `import.meta.url`);
+  - top-level `await` (для рядка `await runRuleCli(...)`);
+  - `process.exit` (Node/Bun).
+- `import.meta.dirname` потребує сучасних версій Node.js (≥ 20.11 / 21.2) або Bun, де ця властивість підтримується.
+
+## Потік виконання / Використання
+
+### Library mode (виклик з оркестратора)
+
+1. Інший модуль (CLI-агрегатор правил, наприклад, диспетчер `@nitra/cursor fix`) імпортує named-export:
+   ```js
+   import { run } from '@nitra/cursor/rules/ci4/fix.mjs'
+   ```
+2. Підготовляє спільний контекст `ctx` (наприклад, спільний `walkCache`).
+3. Викликає:
+   ```js
+   const exitCode = await run(ctx)
+   ```
+4. `run` делегує виклик у `runStandardRule(ruleDir, ctx)`, який послідовно:
+   - перевіряє `applies` (чи правило застосовне);
+   - якщо так — виконує JS-concerns, policy, mdc-refs;
+   - агрегує результат і повертає 0/1.
+5. Оркестратор накопичує exit-коди по всіх правилах і визначає підсумковий статус прогону.
+
+### Standalone mode (CLI)
+
+1. Користувач/CI запускає файл напряму:
+   ```bash
+   bun npm/rules/ci4/fix.mjs
+   ```
+2. `isRunAsCli(import.meta.url)` повертає `true`, оскільки модуль є entry-point процесу.
+3. Викликається `runRuleCli(import.meta.dirname)`:
+   - завантажується конфігурація проекту;
+   - застосовується whitelist (які файли/директорії обходити);
+   - усередині використовується той самий `runStandardRule`, що й у library-режимі;
+   - друкується підсумкова таблиця (summary).
+4. Результат (0/1) передається в `process.exit(...)` — процес завершується відповідним кодом.
+
+Цей режим є повним функціональним еквівалентом команди:
+
+```bash
+npx @nitra/cursor fix ci4
+```
+
+### Інваріанти й типові помилки
+
+- Файл свідомо порожній від прикладної логіки: будь-яка зміна поведінки правила `ci4` має робитися в супутніх файлах (`check-*.mjs`, `applies.mjs`, тощо) — а не тут.
+- Дві ролі (library + standalone) реалізовано в одному файлі навмисно — щоб уникнути дублікатів і щоб CLI-режим завжди узгоджувався з library-режимом.
+- Якщо файл імпортують як модуль (не як entry-point), `isRunAsCli` повертає `false` і блок `process.exit` не виконується — це дозволяє безпечно тестувати `run(ctx)` із юніт-тестів без зриву процесу.
+
+## Rebuild Test
+
+Якщо файл відновлювати «з нуля» за цією документацією, мінімальна реалізація має містити:
+
+1. Імпорт `isRunAsCli, runRuleCli` з `../../scripts/lib/run-rule-cli.mjs`.
+2. Імпорт `runStandardRule` з `../../scripts/lib/run-standard-rule.mjs`.
+3. Named-export `run(ctx)`, який повертає `runStandardRule(import.meta.dirname, ctx)`.
+4. JSDoc для `run` з типом `ctx` (`RuleContext` із `run-standard-rule.mjs`) і `@returns {Promise<number>}`.
+5. Сторожовий блок:
+   ```js
+   if (isRunAsCli(import.meta.url)) {
+     process.exit(await runRuleCli(import.meta.dirname))
+   }
+   ```
+6. ESLint-disable коментар над `process.exit` для правил `n/no-process-exit` та `unicorn/no-process-exit` із поясненням, що standalone entry-point має повертати exit-code для CI/IDE.
+
+Поведінкові інваріанти, які мають бути збережені:
+
+- Імпорт модуля без запуску не повинен викликати `process.exit`.
+- `run()` без аргументів має працювати (опціональний `ctx`).
+- `run(ctx)` повертає саме те значення, яке повернув `runStandardRule`, без додаткової обробки.
+- Standalone-запуск має повертати той самий exit-код, що й `runRuleCli(...)`.

package/rules/ci4/js/docs/marksman_config.md

@@ -0,0 +1,128 @@
+# marksman_config.mjs
+
+## Огляд
+
+Модуль `marksman_config.mjs` — це концерн правила `ci4` (`ci4.mdc`), що відповідає за матеріалізацію canonical-конфіга для Marksman LSP у корені проєкту. Модуль експортує єдину функцію `check`, яка перевіряє наявність файлу `.marksman.toml` у заданому робочому каталозі (`cwd`) і, якщо файлу немає, копіює туди baseline-варіант, що поставляється з пакета `@nitra/cursor`.
+
+Призначення модуля — забезпечити стабільне, передбачуване середовище для Marksman LSP, який використовується для роботи з Markdown-документами в репо (ADR, документація, README). Без явного `.marksman.toml` Marksman використовує свої вбудовані дефолти, які НЕ збігаються з вимогами правила `ci4.mdc`:
+
+- `ci4.mdc` вимагає увімкненого GLFM (GitHub-Flavored Markdown) — для підтримки `> [!NOTE]`-alerts, таблиць, `- [ ]` task-lists.
+- `ci4.mdc` вимагає стилю wiki-link-посилань `file-stem` (ADR-slug дорівнює імені файлу без розширення), а дефолт Marksman — `title-slug-ref`.
+
+Модуль ідемпотентний: якщо `.marksman.toml` уже існує у `cwd` (навіть із ручними кастомними правками користувача), він НЕ перетирається. Користувач отримає тільки звіт про факт існування, а ручні модифікації зберігаються між прогонами.
+
+Файл цілеспрямовано копіюється у `cwd` (а не глибше у дерево), бо Marksman визначає workspace-root за розташуванням свого `.marksman.toml`. Розташування файлу в корені репозиторію дає Marksman можливість бачити одночасно директорії `docs/` та `README.md` усіх workspaces як один загальний workspace.
+
+## Експорти / API
+
+Модуль експортує одну named-функцію:
+
+- `check(cwd?: string): Promise<number>` — асинхронна перевірка/матеріалізація `.marksman.toml`.
+
+Інших публічних експортів немає. Внутрішні константи (`HERE`, `MARKSMAN_BASELINE_PATH`, `MARKSMAN_TARGET_FILENAME`) — module-private і не призначені для прямого використання ззовні.
+
+## Функції
+
+### `check(cwd?)`
+
+**Сигнатура:**
+
+```js
+export async function check(cwd = process.cwd()): Promise<number>
+```
+
+**Параметри:**
+
+- `cwd` (`string`, опціональний) — абсолютний шлях до кореня проєкту, де має бути матеріалізований `.marksman.toml`. Значення за замовчуванням — `process.cwd()`. Дефолт зроблено для сумісності з прямим викликом із CLI (без передачі аргументів).
+
+**Повертає:**
+
+- `Promise<number>` — exit-код перевірки, отриманий через `reporter.getExitCode()`:
+  - `0` — успіх. Можливі підстани:
+    - Файл `.marksman.toml` уже існував у `cwd` (репортується через `reporter.pass(...)`, нічого не змінюється).
+    - Файл був успішно створений із canonical baseline (репортується через `reporter.pass(...)` з префіксом «створено з canonical baseline»).
+  - `1` — фейл. Підстава: canonical baseline (`data/marksman_config/marksman.baseline.toml`) відсутній всередині самого пакета `@nitra/cursor` — означає, що пакет встановлений некоректно. Користувачу пропонується перевстановити `@nitra/cursor`.
+
+**Алгоритм:**
+
+1. Створити instance `reporter` через `createCheckReporter()` із `scripts/lib/check-reporter.mjs`.
+2. Перевірити, що baseline-файл усередині пакета існує (`existsSync(MARKSMAN_BASELINE_PATH)`).
+   - Якщо НЕ існує — викликати `reporter.fail(...)` з повідомленням про зламану установку та повернути exit-код (це буде `1`).
+3. Сформувати цільовий шлях `target = join(cwd, '.marksman.toml')`.
+4. Перевірити, чи `target` уже існує (`existsSync(target)`).
+   - Якщо існує — викликати `reporter.pass(...)` із повідомленням «`.marksman.toml` існує (<relative-шлях>)» і повернути exit-код (`0`). Файл НЕ перезаписується.
+5. Якщо файл НЕ існує — скопіювати baseline у `target` через `await copyFile(MARKSMAN_BASELINE_PATH, target)`.
+6. Викликати `reporter.pass(...)` з повідомленням «`.marksman.toml` створено з canonical baseline (<relative-шлях>) (ci4.mdc)» і повернути exit-код (`0`).
+
+**Side effects:**
+
+- Читання файлової системи: два виклики `existsSync` (синхронно).
+- Запис у файлову систему: один виклик `copyFile` — створює файл `<cwd>/.marksman.toml`, копіюючи вміст із baseline-файлу пакета. Існуючі файли НЕ перезаписуються.
+- Виклики `reporter.pass(...)` / `reporter.fail(...)` мають свої побічні ефекти (typovo — вивід у stdout/stderr, акумуляція стану звіту в `reporter`). Деталі залежать від реалізації `createCheckReporter`.
+
+**Помилки:**
+
+- Якщо `copyFile` кине помилку (наприклад, через відсутність прав запису в `cwd` чи фізично заповнений диск) — вона НЕ перехоплюється всередині `check` і прокинеться вище, в caller. Caller відповідає за відлов і репорт.
+- Якщо `cwd` не існує — `copyFile` теж кине ENOENT.
+
+## Залежності
+
+### Імпорти з Node.js стандартної бібліотеки
+
+- `existsSync` із `node:fs` — синхронна перевірка існування файлів. Використовується двічі: для baseline і для target.
+- `copyFile` із `node:fs/promises` — асинхронне копіювання файлу.
+- `dirname`, `join`, `relative` із `node:path` — конструювання та форматування шляхів:
+  - `dirname` — отримати директорію поточного модуля.
+  - `join` — сконструювати абсолютний шлях до baseline та цільового файлу.
+  - `relative` — обчислити шлях відносно `cwd` для людиночитного логування.
+- `fileURLToPath` із `node:url` — конвертувати `import.meta.url` у файловий шлях (ESM-патерн отримання `__dirname`).
+
+### Внутрішні залежності проєкту
+
+- `../../../scripts/lib/check-reporter.mjs` — модуль, що експортує `createCheckReporter`. Реалізує уніфікований інтерфейс репорту для concern-функцій правил: методи `pass(message)`, `fail(message)` і `getExitCode()`. Усі concern-модулі правил `ci4` (та інші правила) використовують цей репортер для єдиного UX.
+
+### Файлові залежності (data assets)
+
+- `./data/marksman_config/marksman.baseline.toml` — canonical-baseline TOML-конфіг Marksman LSP, що поставляється разом із пакетом `@nitra/cursor`. Цей файл — джерело правди для дефолтного `.marksman.toml`. Якщо файл відсутній — `check` поверне `1`.
+
+## Потік виконання / Використання
+
+### Типовий контекст виклику
+
+Модуль викликається фреймворком правил `ci4.mdc` як один із concern-чеків (поряд із іншими файлами у `npm/rules/ci4/js/`). Кожен concern перевіряє один аспект конфігурації проєкту відповідно до правила `ci4.mdc`. `marksman_config` відповідає за аспект «Marksman LSP має консистентну конфігурацію».
+
+### Інтеграція
+
+1. Зовнішній runner (зазвичай CLI `n-cursor` або агрегатор правил) імпортує `check` і викликає його:
+   ```js
+   import { check } from '@nitra/cursor/npm/rules/ci4/js/marksman_config.mjs'
+   const code = await check(process.cwd())
+   process.exit(code)
+   ```
+2. `check` повертає exit-код:
+   - `0` — concern пройдений, можна продовжувати.
+   - `1` — fatal, треба зупинитися або репортувати юзеру.
+
+### Сценарії
+
+- **Свіжий клон репо без `.marksman.toml`**: на першому прогоні правила `ci4` файл буде створений із baseline. Подальші прогони побачать існуючий файл і не змінюватимуть його.
+- **Користувач уже має кастомний `.marksman.toml`**: модуль НЕ перетирає його. Користувач може налаштувати Marksman під свої потреби (наприклад, додати specific completion-теги), і ця конфігурація переживе всі майбутні запуски `ci4`.
+- **Зламана установка `@nitra/cursor` (baseline відсутній)**: модуль миттєво повертає `1` із пояснювальним повідомленням про необхідність перевстановити пакет. Жодних змін у `cwd` не вноситься.
+
+### Ідемпотентність і безпека
+
+- Функція ідемпотентна: повторні виклики на тому самому `cwd` дають однаковий результат — або `0` із пояснювальним «існує», або `0` із «створено» лише на першому прогоні.
+- Безпека для користувацьких правок: модуль НЕ змінює існуючий `.marksman.toml`, навіть якщо його вміст застарів чи розходиться з baseline. Це свідома trade-off на користь юзерських кастомізацій. Якщо потрібно примусове оновлення baseline — користувач має видалити файл вручну.
+
+## Rebuild Test
+
+Перевірка повноти документації — чи можна за цим описом відтворити поведінку модуля з нуля без перегляду коду:
+
+- Public API: `check(cwd?)` — задокументовано (сигнатура, дефолт, повернення, exit-коди).
+- Алгоритм: 6 кроків (reporter → перевірка baseline → формування target → перевірка target → copy → repоrt) — задокументовано.
+- Залежності: всі імпорти (`node:fs`, `node:fs/promises`, `node:path`, `node:url`, `check-reporter.mjs`, baseline TOML) — перелічено з призначенням.
+- Side effects: I/O (read+write), вивід у репортер — описано.
+- Граничні випадки: відсутній baseline (exit 1), існуючий target (no-op, exit 0), створення нового файлу (exit 0), помилки copyFile (прокидаються нагору) — описано.
+- Контекст і мотивація: чому файл у `cwd`, чому НЕ перезаписується, чому потрібен явний конфіг (GLFM, file-stem) — описано.
+
+Реконструкція коду на основі цього документа повинна давати функціонально еквівалентний модуль.

package/rules/docker/docker.mdc

@@ -1,6 +1,6 @@
 ---
 description: Dockerfile — lint-docker / hadolint; перевірка check-docker
-version: '1.11'
+version: '1.12'
 globs: "**/Dockerfile*"
 alwaysApply: false
 ---
@@ -13,7 +13,7 @@ alwaysApply: false
 
 - **backend (типово)**: `mirror.gcr.io/library/alpine:*`
 - **ультра-легкі (glibc / одна статична збірка)**: `scratch` — тільки як `FROM scratch` (офіційний порожній базовий шар), коли весь **runtime** уже в `COPY --from=…`
-- **glibc, Debian (slim)**: `mirror.gcr.io/library/debian:*` **лише** з тегом, у якому є `slim` (наприклад `bookworm-slim`, `trixie-slim`), а не `bookworm` без `slim`
+- **glibc, Debian (slim)**: `mirror.gcr.io/library/debian:*` **лише** з тегом, у якому є `slim` (наприклад `bookworm-slim`, `trixie-slim`), а не `bookworm` без `slim`. Debian-slim виправданий **лише** коли потрібен саме glibc-рантайм (нативні glibc-залежності, prebuilds без musl-варіанта). **Non-root сам по собі не є підставою** переходити сюди: `mirror.gcr.io/oven/bun:alpine` уже має користувача `bun` (uid/gid 1000), тож `USER bun` дає non-root **без зміни бази**. Перехід Alpine→Debian заради лише non-root — **антипатерн** (більший образ + зайва musl→glibc міграція bun-бінарника)
 - **виняток (інтерпретовані стеки)**: `mirror.gcr.io/library/php:*` або `mirror.gcr.io/library/python:*` — якщо сервіс має крутитися в офіційному runtime PHP чи Python, а не як один бінарник на Alpine; інакше лишай **alpine** у фінальному stage
 - **frontend**: `mirror.gcr.io/nginxinc/nginx-unprivileged:*` або `mirror.gcr.io/openresty/openresty:*`
 
@@ -102,7 +102,12 @@ CMD ["bun", "src/index.js"]
 
 ## не превілейований образ
 
-Для всих образів потрібно щоб використовувся non root принцип, наприклад:
+Для всіх образів потрібно щоб використовувся non-root принцип. **Спосіб** досягнення non-root залежить від **бази**, а не від зміни ОС — змінювати дистрибутив (Alpine→Debian) заради лише non-root **не треба**. Два шляхи:
+
+- **standalone-бінарник на `alpine:latest`** (секція «компіляція») — у `alpine` немає готового non-root користувача, тож його створюємо явно: `addgroup -g 1000 app && adduser -D -u 1000 -G app app` + `COPY --chown=app:app` + `USER app` (приклад нижче);
+- **ship `node_modules` на `mirror.gcr.io/oven/bun:alpine`** (секція «виняток: нативний `.node`-аддон») — користувач `bun` (uid/gid 1000) **уже в базі**, тож достатньо `COPY --chown=bun:bun …` + `USER bun`; базу на Debian-slim міняти **не треба** — це той самий антипатерн, що й у переліку фінальних образів вище.
+
+Приклад для standalone-бінарника на alpine:
 
 ```dockerfile
 # Stage 1

package/rules/docker/docs/fix.md

@@ -0,0 +1,171 @@
+# fix.mjs — entry-point правила `docker` (fix-режим)
+
+## Огляд
+
+Файл `npm/rules/docker/fix.mjs` — це тонкий **entry-point** правила `docker` у пакеті `@nitra/cursor` для режиму `fix` (автоматичне виправлення порушень). Він не містить власної логіки перевірки чи виправлень: уся реальна робота делегується у спільні бібліотечні функції з `npm/scripts/lib/`.
+
+Файл виконує **дві ролі** одночасно (патерн dual-role module, прийнятий в усіх `rules/<id>/fix.mjs` цього репозиторію):
+
+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. **applies** — перевірка, чи правило взагалі релевантне для поточного workspace.
+2. **JS-concerns** — JS-специфічні fix-перевірки (з теки `js/`).
+3. **policy** — політики/policy-перевірки правила.
+4. **mdc-refs** — узгодження посилань у файлі `docker.mdc` (опис правила для Cursor).
+
+ID правила (`docker`) визначається автоматично з імені директорії-носія через `import.meta.dirname` — у `fix.mjs` немає жодного хардкоду ID.
+
+## Експорти / API
+
+| Експорт     | Тип                      | Призначення                                                                                                                                    |
+| ----------- | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| `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, unicorn/no-process-exit
+  process.exit(await runRuleCli(import.meta.dirname))
+}
+```
+
+Семантично та функціонально такий код тотожний оригіналу: дві ролі модуля (library `run` + standalone main), делегування у `runStandardRule`/`runRuleCli`, ID правила визначається через `import.meta.dirname`, exit-код процесу повертається лише у standalone-режимі.