@nitra/cursor 12.6.1 → 12.7.0

package/rules/doc-files/{js/lint.mjs → main.mjs}

@@ -2,7 +2,19 @@
 import { join, dirname, basename, extname } from 'node:path'
 import { existsSync, readdirSync } from 'node:fs'
 
-import { describeFile, isDocCandidate, isSourceFile, scanForDocFiles } from './docgen-scan.mjs'
+import { describeFile, isDocCandidate, isSourceFile, scanForDocFiles, scanOrphanedDocs } from './js/docgen-scan.mjs'
+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); `lint()` нижче — lint-поверхня (детект застарілих файлових док), імпл інлайн тут.
+ * @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)
+}
 
 /** Дока живе у `<dir>/docs/<stem>.md`; повертає `<dir>/<stem>` для реверс-мапінгу. */
 const DOC_MD_RE = /(?:^|\/)docs\/[^/]+\.md$/u
@@ -89,14 +101,52 @@ function collectStale(files, cwd) {
  */
 export async function lint(files, cwd = process.cwd(), { readOnly = false, llmFix = false } = {}) {
   const stale = collectStale(files, cwd)
-  if (stale.length === 0) return 0
-  if (readOnly || !llmFix) return reportStale(stale)
+  // Orphan-детект тільки при повному скані; при точковому (files визначено) — не релевантно
+  const orphans = files === undefined ? scanOrphanedDocs(cwd) : []
+
+  if (stale.length === 0 && orphans.length === 0) return 0
+  if (readOnly || !llmFix) {
+    if (stale.length > 0) reportStale(stale)
+    if (orphans.length > 0) {
+      const list = orphans.map(f => `  - ${f}`).join('\n')
+      process.stderr.write(
+        `✗ doc-files: сирітських доків (source видалено) ${orphans.length}:\n${list}\n→ очисти: npx @nitra/cursor fix-doc-files\n`
+      )
+    }
+    return 1
+  }
+
+  // fix-by-default: opportunistic-генерація stale + purge orphans.
+  // omlx недоступний → runGenerationBatch друкує причину й повертає !=0;
+  // purgeOrphanedDocs не залежить від LLM і виконується завжди.
+  if (stale.length > 0) {
+    process.stdout.write(`ℹ️  doc-files: ${stale.length} застарілих — пробую авто-фікс (omlx)…\n`)
+  }
+  const { runGenerationBatch, purgeOrphanedDocs } = await import('./js/docgen-files-batch.mjs')
+  if (stale.length > 0) {
+    await runGenerationBatch(stale, cwd, { headline: `📋 doc-files: генерація ${stale.length} файл(ів)` })
+  }
+  if (orphans.length > 0) {
+    const deleted = purgeOrphanedDocs(cwd)
+    if (deleted > 0) process.stdout.write(`🗑 doc-files: видалено ${deleted} сирітських доки(ів)\n`)
+  }
+
+  const stillStale = collectStale(files, cwd)
+  const stillOrphans = files === undefined ? scanOrphanedDocs(cwd) : []
+  if (stillStale.length === 0 && stillOrphans.length === 0) return 0
+  if (stillStale.length > 0) reportStale(stillStale)
+  if (stillOrphans.length > 0) {
+    const list = stillOrphans.map(f => `  - ${f}`).join('\n')
+    process.stderr.write(
+      `✗ doc-files: сирітських доків (source видалено) ${stillOrphans.length}:\n${list}\n→ очисти: npx @nitra/cursor fix-doc-files\n`
+    )
+  }
+  return 1
+}
+
+export { runLintDocFilesCli } from './js/run-lint.mjs'
 
-  // fix-by-default: opportunistic-генерація через спільне ядро (preflight omlx →
-  // батч із circuit-breaker'ом). omlx недоступний → runGenerationBatch друкує причину
-  // й повертає !=0; ми re-detect'имо й через reportStale віддаємо exit 1 (гейт тримається).
-  process.stdout.write(`ℹ️  doc-files: ${stale.length} застарілих — пробую авто-фікс (omlx)…\n`)
-  const { runGenerationBatch } = await import('./docgen-files-batch.mjs')
-  await runGenerationBatch(stale, cwd, { headline: `📋 doc-files: генерація ${stale.length} файл(ів)` })
-  return reportStale(collectStale(files, cwd))
+if (isRunAsCli(import.meta.url)) {
+  // Standalone: bun rules/doc-files/main.mjs — повний еквівалент `npx @nitra/cursor check doc-files`.
+  process.exitCode = await runRuleCli(import.meta.dirname)
 }

package/rules/docker/docs/index.md

@@ -9,3 +9,4 @@ resource: npm/rules/docker/
 | Файл | Тип |
 |---|---|
 | [fix.mjs](fix.md) | JS Module |
+| [main.mjs](main.md) | JS Module |

package/rules/docker/docs/main.md

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

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

@@ -3,70 +3,42 @@ type: JS Module
 title: lint.mjs
 resource: npm/rules/docker/js/lint.mjs
 docgen:
-  crc: 495d03ee
+  crc: bf935f19
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 100
 ---
 
-Модуль забезпечує декомпозицію структури Dockerfile для вилучення даних про багатостадійні збірки та залежності середовища. Функції, такі як `findDockerfilePaths` та `splitDockerfileStages`, використовуються для ідентифікації та розділення стадій збірки. Модуль надає інструменти для отримання підказок про виконання, включаючи визначення багатостадійного режиму (`getMultistageAndRuntimeHint`), компіляційних налаштувань (`getBunCompileHint`), та підказок про використання образу Nginx Alpine Slim (`getNginxAlpineSlimTagHint`). Додатково, він визначає необхідність роботи без прав root (`getNonRootRuntimeHint`). (docker.mdc)
+## Огляд
 
-## Поведінка
-
-isDockerfileName
-Перевіряє, чи є вхідний рядок назвою Dockerfile або Containerfile.
-
-findDockerfilePaths
-Збирає абсолютні шляхи до Dockerfile або Containerfile від заданого кореня репозиторію, враховуючи виключені шляхи.
-
-parseFromStages
-Витягує інструкції FROM з вмісту файлу.
-
-splitDockerfileStages
-Розбиває вміст Dockerfile на окремі стадії на основі інструкцій FROM.
-
-getMultistageAndRuntimeHint
-Перевіряє, чи має Dockerfile мінімум дві інструкції FROM і чи є фінальний образ дозволеним runtime-образом (docker.mdc).
+Модуль аналізує файли `Dockerfile` та `Containerfile` у репозиторії, використовуючи `isDockerfileName` та `findDockerfilePaths` для ідентифікації конфігурацій. Він розбиває знайдені файли на етапи за допомогою `parseFromStages` та `splitDockerfileStages`. Модуль перевіряє конфігурацію, використовуючи `check` та `lint`, щоб оцінити відповідність стандартам, враховуючи дані з `package.json`. Він визначає інформацію про багатоетапну збірку, теги образів та права користувача, відповідно до вимог (docker.mdc).
 
-getBunCompileHint
-Перевіряє наявність інструкцій `bun install` та відсутності `bun build --compile` для виявлення необхідності компіляції бінарника (docker.mdc).
-
-getNginxAlpineSlimTagHint
-Перевіряє, чи містить інструкція FROM для образу nginx потрібний тег `alpine-slim` (docker.mdc).
-
-getNonRootRuntimeHint
-Перевіряє, чи присутня інструкція USER у фінальній стадії і чи не використовується `root` або `0` для запуску (docker.mdc).
-
-check
-Запускає перевірки Dockerfile через hadolint, включаючи перевірки multistage, компіляції, non-root, тегів nginx та загальну валідацію.
-
-readNearestDependencies
-Читає залежності з найближчого package.json, розташованого у каталогах Dockerfile або вище.
+## Поведінка
 
-checkDockerfile
-Перевіряє індивідуальний Dockerfile/Containerfile на наявність інструкцій, пов'язаних з mirror.gcr.io, multistage, компіляції, non-root, тегів nginx та виконує перевірку через hadolint.
+isDockerfileName визначає, чи є наданий шлях назвою Dockerfile або Containerfile.
+findDockerfilePaths збирає відсортований список абсолютних шляхів до всіх Dockerfile/Containerfile, ігноруючи вказані шляхи каталогів.
+parseFromStages витягує список усіх інструкцій `FROM <image>` з вмісту Dockerfile/Containerfile.
+splitDockerfileStages розбиває вміст Dockerfile/Containerfile на окремі етапи (stages) на основі інструкцій `FROM`.
+getMultistageAndRuntimeHint перевіряє, чи відповідає структура Dockerfile вимогам multistage build та дозволеним образам для фінального runtime (docker.mdc).
+getBunCompileHint перевіряє, чи виконано необхідну компіляцію застосунку у бінарник для bun-проєктів, якщо фінальний образ — alpine (docker.mdc).
+getNginxAlpineSlimTagHint перевіряє, чи використовується тег `alpine-slim` для nginx-образів (docker.mdc).
+getNonRootRuntimeHint перевіряє, чи має фінальний stage інструкцію `USER <non-root>` для забезпечення не превілейованого образу (docker.mdc).
+check перевіряє всі знайдені Dockerfile/Containerfile, виконуючи перевірки на відповідність стандартам, включаючи hadolint (docker.mdc).
+lint оркеструє обхід репозиторію та викликає `check` для всіх знайдених Dockerfile/Containerfile.
 
 ## Публічний API
 
-isDockerfileName — перевіряє наявність файлів `Dockerfile` або `Containerfile` у назві.
-findDockerfilePaths — збирає повні шляхи до файлів `Dockerfile` або `Containerfile` від поточної робочої директорії.
-parseFromStages — витягує всі інструкції `FROM <image>` з вмісту файлів.
-splitDockerfileStages — розділяє файл `Dockerfile` на послідовні етапи за інструкціями `FROM`. Повертає порожній масив, якщо інструкції `FROM` відсутні.
-getMultistageAndRuntimeHint — перевіряє вимоги до структури Dockerfile:
-  multistage — вимагає мінімум два етапи `FROM`.
-  фінальний FROM — перевіряє, чи дозволений образ у `docker.mdc` (alpine, scratch, debian slim, php, python, nginx, openresty, тощо). Для проєктів з нативним .node-аддоном дозволено `mirror.gcr.io/oven/bun:*` (bun-рантайм).
-getBunCompileHint — перевіряє наявність вимоги "компіляції в бінарник" для bun-проєктів на бекенд-рантаймах.
-Тригер — перевіряє, чи присутній крок `bun install` або `bun i` у Dockerfile.
-Тригер — перевіряє, чи фінальний образ — `mirror.gcr.io/library/alpine:*` (виключаючи фронтенд nginx/openresty).
-getNginxAlpineSlimTagHint — перевіряє, чи містить `FROM` для nginx-образу (`mirror.gcr.io/nginxinc/nginx-unprivileged`) тег `alpine-slim` (`docker.mdc`).
-getNonRootRuntimeHint — перевіряє вимогу "non-root" у фінальному runtime-етапі (`docker.mdc`).
-Очікування — перевіряє, чи містить build stage інструкцію `bun build --compile`.
-Очікування — перевіряє, чи відсутні виклики `bun` у фінальному етапі (залишкові інструменти збірки).
-Очікування — перевіряє, чи містить фінальний етап інструкцію `USER <name|uid>`.
-Очікування — перевіряє, чи користувач у фінальному етапі не є `root` і не дорівнює `0`.
-check — виконує перевірку через hadolint (`docker.mdc`).
+isDockerfileName — визначає, чи є файл `Dockerfile` або `Containerfile` у поточному каталозі.
+findDockerfilePaths — збирає повні шляхи до файлів `Dockerfile` або `Containerfile` від кореня робочого каталогу.
+parseFromStages — витягує всі образи, зазначені в інструкціях `FROM` у файлі.
+splitDockerfileStages — розділяє вміст файлу на окремі етапи згідно з інструкціями `FROM`.
+getMultistageAndRuntimeHint — оцінює відповідність структури файлу: мінімум два етапи `FROM` та відповідність базових образів списку дозволених у `docker.mdc` (з додатковим дозволом для `bun` у випадку нативного `.node-аддону`).
+getBunCompileHint — перевіряє, чи вимагає проєкт на базі Bun компіляції в бінарний файл для бекенд-рантайму.
+getNginxAlpineSlimTagHint — перевіряє, чи використовується тег `alpine-slim` для образів Nginx, як зазначено в `docker.mdc`.
+getNonRootRuntimeHint — перевіряє, чи встановлено користувача, відмінного від `root` (не `0`), у фінальному етапі виконання, згідно з `docker.mdc`.
+check — виконує статичний аналіз файлу `Dockerfile`/`Containerfile` за допомогою hadolint (`docker.mdc`).
+lint — запускає стандартний лінтер для Docker-файлів через адаптер `n-cursor lint docker`.
 
 ## Гарантії поведінки
 
-- Read-only: файл не виконує операцій запису у файлову систему.
+- Read-only: не виконує операцій запису (ФС/БД).
 - Перехоплює помилки і не пропускає винятків назовні (fail-safe).
-- За невдалої перевірки повертає `false`/`null` замість винятку.
-- Не звертається до мережі.

package/rules/docker/js/lint.mjs

@@ -1,6 +1,7 @@
 /** @see ./docs/lint.md */
 import { readFile } from 'node:fs/promises'
 import { basename, dirname, join } from 'node:path'
+import { runStandardLint } from '../../../scripts/lib/run-standard-lint.mjs'
 
 import { getMirrorGcrHint, getFromImageToken } from '../lib/docker-mirror.mjs'
 import { getNativeAddonDeps, getNativeAddonNoCompileHint } from '../lib/docker-native-addon.mjs'
@@ -369,3 +370,13 @@ async function checkDockerfile(reporter, root, abs) {
     fail(`${rel} (${via})${detail}`)
   }
 }
+
+/**
+ * Оркестраторний адаптер `n-cursor lint docker`: обгортає `check()` у `runStandardLint` (лок).
+ * @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, () => check(cwd))
+}

package/rules/docker/lib/docker-hadolint.mjs

@@ -4,7 +4,7 @@
  * Відносні шляхи з прямими слешами; hadolint резолвиться через `ensureTool`
  * (PATH → кеш → авто-install brew/scoop/GitHub Release per-platform). Docker-fallback
  * прибрано — hadolint ставиться як **нативний бінарник**, без `docker run`.
- * Використовується `./check.mjs` (check-docker) та `../../lint/lint.mjs` (run-docker).
+ * Використовується `../js/lint.mjs` (правило `n-cursor lint docker` / check-docker).
  */
 import { spawnSync } from 'node:child_process'
 import { relative, sep } from 'node:path'

package/rules/docker/lib/docs/docker-hadolint.md

@@ -3,186 +3,29 @@ type: JS Module
 title: docker-hadolint.mjs
 resource: npm/rules/docker/lib/docker-hadolint.mjs
 docgen:
-  crc: b97701f3
+  crc: ebab2135
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 90
 ---
 
-Модуль `docker-hadolint.mjs` інкапсулює спільну логіку запуску статичного аналізатора `hadolint` для перевірки `Dockerfile`-ів у межах правила `docker` (див. `.cursor/rules/docker.mdc` / `n-docker`). Він є тонким адаптером поверх системного бінарника `hadolint` та надає двом викликачам — `check.mjs` (skill `check-docker`) і `../../lint/lint.mjs` (skill `run-docker`) — єдину функцію перевірки одного `Dockerfile` плюс утиліту нормалізації шляхів.
+## Огляд
 
-Ключові архітектурні рішення:
+Спільна логіка виклику hadolint для шляхів до Dockerfile. Модуль створює стандартизовані відносні шляхи з прямими слешами. Він ініціює перевірку Dockerfile, використовуючи hadolint як нативний бінарник, який резолвиться через `ensureTool` (PATH → кеш → авто-install brew/scoop/GitHub Release per-platform). Для отримання інформації про встановлення можна звертатися до https://github.com/hadolint/hadolint/releases. Публічна функція `lintDockerfileWithHadolint` виконує перевірку за правилом `n-cursor lint docker` / check-docker.
 
-- `hadolint` запускається **виключно як нативний бінарник**. Будь-який Docker-fallback (наприклад, `docker run hadolint/hadolint`) свідомо прибраний, тож модуль не залежить від запущеного Docker Engine.
-- Розв’язання шляху до бінарника делеговано в `ensureTool('hadolint')`, який реалізує ланцюжок `PATH → локальний кеш інструментів → авто-install` через `brew` / `scoop` / GitHub Release, відповідно до платформи.
-- Якщо `ensureTool` падає (інструмент відсутній і авто-install вимкнено через `N_CURSOR_NO_AUTO_INSTALL` або фізично не вдався), модуль **не кидає виняток назовні**, а повертає структурований результат `{ ok: false, stderr: <інструкція з установки> }`. Це дозволяє викликачам однаково обробляти і реальні порушення hadolint, і відсутність інструмента.
-- Шляхи у виводі нормалізуються через `posixRel` (відносно `root`, з прямими слешами `/`), щоб лог і повідомлення про помилки були стабільними між macOS / Linux / Windows.
+## Поведінка
 
-## Експорти / API
+posixRel
+Створює відносний шлях від кореня з використанням прямих слешів.
 
-Модуль є ESM (`.mjs`) і має два іменовані експорти:
+lintDockerfileWithHadolint
+Запускає hadolint як нативний бінарник для перевірки Dockerfile. Якщо не вдається знайти hadolint, повертає помилку з інструкцією для встановлення (наприклад, https://github.com/hadolint/hadolint/releases).
 
-| Експорт                                     | Тип      | Призначення                                                                        |
-| ------------------------------------------- | -------- | ---------------------------------------------------------------------------------- |
-| `posixRel(root, absPath)`                   | function | Перетворити абсолютний шлях на відносний від `root` з прямими слешами.             |
-| `lintDockerfileWithHadolint(root, absPath)` | function | Запустити `hadolint` для одного `Dockerfile` і повернути структурований результат. |
+## Публічний API
 
-Default-експорту немає. Глобальних побічних ефектів на рівні модуля немає — імпорт лише підтягує `ensureTool`, не виконуючи його.
+* posixRel — Генерує абсолютний шлях від кореня з використанням лише слешів, забезпечуючи стабільність незалежно від операційної системи.
+* lintDockerfileWithHadolint — Запускає інструмент hadolint для аналізу Dockerfile. Якщо інструмент не знайдено у системних шляхах, він намагається встановити його. У разі невдачі встановлення або відключення автоматичного встановлення, повертає помилку, надаючи користувачеві підказку для ручного запуску (детальніше про інструмент можна знайти на https://github.com/hadolint/hadolint/releases).
 
-## Функції
+## Гарантії поведінки
 
-### `posixRel(root, absPath)`
-
-Утиліта нормалізації шляхів для стабільного логування й передачі в `hadolint`.
-
-**Сигнатура:**
-
-```js
-export function posixRel(root: string, absPath: string): string
-```
-
-**Параметри:**
-
-- `root` — абсолютний шлях до кореня репозиторію (або будь-якого опорного каталогу), відносно якого треба отримати шлях.
-- `absPath` — абсолютний шлях до файлу, який треба представити відносно `root`.
-
-**Повертає:**
-
-- Рядок із відносним шляхом, де всі системні розділювачі (`path.sep`) замінено на прямий слеш `/`. На POSIX-системах результат фактично збігається з `path.relative`, на Windows — конвертує `\` на `/`.
-
-**Алгоритм:**
-
-1. Викликає `relative(root, absPath)` з `node:path` для обчислення відносного шляху.
-2. Розбиває результат за поточним `sep` (`path.sep`) і склеює знову через `'/'`.
-
-**Side effects:** немає; функція чиста й детермінована.
-
-**Примітка:** функція не валідовує, чи `absPath` справді абсолютний і чи він знаходиться під `root` — у такому випадку `relative` поверне відносний шлях із `..`, що теж буде нормалізовано до прямих слешів.
-
----
-
-### `lintDockerfileWithHadolint(root, absPath)`
-
-Основна точка входу модуля: виконує `hadolint` для одного `Dockerfile` і повертає уніфікований результат.
-
-**Сигнатура:**
-
-```js
-export function lintDockerfileWithHadolint(
-  root: string,
-  absPath: string
-): {
-  ok: boolean,
-  stdout: string,
-  stderr: string,
-  via: string
-}
-```
-
-**Параметри:**
-
-- `root` — абсолютний шлях до кореня репозиторію. Використовується одночасно як `cwd` для дочірнього процесу і як база для `posixRel`.
-- `absPath` — абсолютний шлях до конкретного `Dockerfile` (або файлу, який треба перевірити hadolint’ом).
-
-**Повертає об’єкт із полями:**
-
-- `ok` — `true`, якщо `hadolint` завершився з кодом виходу `0` (порушень немає). `false` — у будь-якому іншому випадку: інструмент знайшов проблеми, не запустився, або не зміг бути встановленим/знайденим.
-- `stdout` — stdout процесу hadolint як рядок (UTF-8). При помилці отримання інструмента — порожній рядок.
-- `stderr` — stderr процесу hadolint як рядок. Якщо інструмент не вдалося отримати, тут міститься українська інструкція з установки (`brew install hadolint` / `scoop install hadolint` / посилання на GitHub Releases) разом із повідомленням оригінальної помилки.
-- `via` — завжди константа `'hadolint'`. Поле залишене для зворотної сумісності з API, де раніше міг бути ще варіант на кшталт `'docker'`; зараз інших значень не повертається.
-
-**Алгоритм:**
-
-1. Обчислює відносний шлях `rel = posixRel(root, absPath)`.
-2. Намагається отримати шлях до бінарника через `hadolintPath = ensureTool('hadolint')`.
-   - Якщо `ensureTool` кидає виняток, функція **перехоплює** його і повертає об’єкт з `ok: false`, порожнім `stdout`, інструктивним `stderr` (текст помилки + поради з установки) і `via: 'hadolint'`. На цьому виконання завершується.
-3. Викликає `spawnSync(hadolintPath, [rel], { cwd: root, encoding: 'utf8', maxBuffer: 10 * 1024 * 1024 })`:
-   - `cwd: root` — щоб hadolint бачив правильну робочу директорію і `rel` коректно резолвився.
-   - `encoding: 'utf8'` — `stdout`/`stderr` одразу приходять як рядки, а не `Buffer`.
-   - `maxBuffer: 10 МіБ` — захист від великих обсягів виводу при множинних попередженнях.
-4. Формує результат: `ok = local.status === 0`, `stdout`/`stderr` приходять з процесу (з фолбеком на порожній рядок через `??`), `via: 'hadolint'`.
-
-**Side effects:**
-
-- Може ініціювати **авто-install** `hadolint` через `ensureTool` (мережа, brew/scoop/завантаження GitHub Release, запис у локальний кеш інструментів), якщо інструмент відсутній і авто-install не вимкнено `N_CURSOR_NO_AUTO_INSTALL`.
-- Синхронно запускає дочірній процес `hadolint`, що блокує цикл подій Node.js до завершення (через `spawnSync`).
-- Не пише в stdout/stderr поточного процесу самостійно — увесь вивід hadolint повертає викликачу.
-- Не змінює `process.cwd()` поточного процесу (тільки `cwd` дочірнього).
-
-**Обробка помилок:**
-
-- Виняток від `ensureTool` ловиться і конвертується у м’який `ok: false` з підказкою.
-- Помилки запуску `spawnSync` (наприклад, права доступу) **не обгортаються окремо**: у такому разі `spawnSync` повертає об’єкт з `status: null` і `error`-полем, відповідно `ok` буде `false`, а `stdout`/`stderr` — порожніми (через `??`). Поле `error` об’єкта `spawnSync` у результат не транслюється.
-- Ненульовий `status` від самого `hadolint` (тобто знайдені порушення) трактується як `ok: false`, але `stderr`/`stdout` несуть звіт hadolint для подальшого парсингу/виводу користувачу.
-
-## Залежності
-
-### Node.js (стандартні)
-
-- `node:child_process` — імпортується `spawnSync` для синхронного запуску `hadolint`.
-- `node:path` — імпортуються `relative` і `sep` для побудови відносного шляху з нормалізацією роздільників.
-
-### Внутрішні (моноpепо)
-
-- `../../../scripts/lib/ensure-tool.mjs` — функція `ensureTool(name)`, яка:
-  - повертає абсолютний шлях до бінарника;
-  - намагається знайти його у `PATH`, у локальному кеші інструментів;
-  - за потреби виконує авто-install через `brew` (macOS), `scoop` (Windows) чи GitHub Release (Linux);
-  - кидає виняток, якщо інструмент недоступний і авто-install неможливий / вимкнено `N_CURSOR_NO_AUTO_INSTALL`.
-
-### Зовнішні (runtime)
-
-- Бінарник `hadolint` (нативний; брати з `brew`, `scoop`, GitHub Release). **Не** використовується `docker run hadolint/hadolint` — Docker-fallback явно прибраний.
-
-### Імпорт-споживачі (всередині правила `docker`)
-
-- `./check.mjs` — скіл `check-docker`: разова перевірка обраних `Dockerfile`-ів.
-- `../../lint/lint.mjs` — скіл `run-docker`: інтеграція в загальний `lint`-конвеєр.
-
-## Потік виконання / Використання
-
-Типовий сценарій використання модуля викликачем:
-
-1. Викликач (наприклад, `check-docker` або `run-docker`) визначає `root` репозиторію і список абсолютних шляхів до `Dockerfile`-ів.
-2. Для кожного шляху викликається `lintDockerfileWithHadolint(root, absPath)`.
-3. Модуль:
-   - нормалізує шлях у POSIX-форму (`posixRel`);
-   - резолвить `hadolint` через `ensureTool` (можливо з авто-install);
-   - синхронно запускає `hadolint <rel>` у `cwd = root`;
-   - повертає `{ ok, stdout, stderr, via }`.
-4. Викликач інтерпретує результат:
-   - `ok === true` → файл чистий, нічого не виводити (або вивести позитивний статус);
-   - `ok === false` → показати `stdout`/`stderr` користувачу, зарахувати як порушення; якщо `stderr` містить інструкцію з установки — повідомити користувача, як отримати інструмент.
-
-### Приклад використання
-
-```js
-import { lintDockerfileWithHadolint, posixRel } from './docker-hadolint.mjs'
-
-const root = process.cwd()
-const absPath = '/abs/path/to/repo/services/api/Dockerfile'
-
-const result = lintDockerfileWithHadolint(root, absPath)
-
-if (!result.ok) {
-  console.error(`hadolint failed for ${posixRel(root, absPath)} (via=${result.via})`)
-  if (result.stdout) console.error(result.stdout)
-  if (result.stderr) console.error(result.stderr)
-  process.exitCode = 1
-}
-```
-
-### Поведінка за відсутності `hadolint`
-
-- Якщо `hadolint` відсутній і `N_CURSOR_NO_AUTO_INSTALL` **не** виставлена, `ensureTool` спробує встановити бінарник автоматично (за платформою).
-- Якщо `N_CURSOR_NO_AUTO_INSTALL` виставлена або авто-install не вдався, `lintDockerfileWithHadolint` повертає:
-  - `ok: false`,
-  - `stdout: ''`,
-  - `stderr: 'Не вдалося отримати hadolint (<повідомлення>). Встанови: brew install hadolint (macOS) / scoop install hadolint (Windows) / https://github.com/hadolint/hadolint/releases (Linux).'`,
-  - `via: 'hadolint'`.
-- Завдяки м’якій обробці викликач може коректно показати інструкцію користувачу замість аварійного завершення.
-
-### Особливості та обмеження
-
-- **Синхронність**: усі виклики блокуючі (`spawnSync`). Для пакетної перевірки сотень файлів варіант — викликати модуль із зовнішнього оркестратора, який сам керує паралелізмом (з урахуванням обмежень середовища).
-- **Один файл за виклик**: функція передає у `hadolint` рівно один аргумент `rel`. Для масової перевірки слід викликати функцію в циклі — це свідомий вибір, щоб уніфікувати результат і прив’язку до конкретного файлу.
-- **Розмір буфера**: `maxBuffer = 10 МіБ` достатньо для звичайних `Dockerfile`-звітів; для аномально великих виводів значення доведеться змінювати на рівні форку модуля.
-- **`via` константно `'hadolint'`**: поле залишене для майбутньої сумісності, але наразі ніколи не приймає інших значень.
-- **Стабільність шляхів**: завдяки `posixRel` повідомлення про порушення містять однакові шляхи з прямими слешами на всіх ОС — це важливо для дифу логів у CI.
+- Read-only: не виконує операцій запису (ФС/БД).
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).

package/rules/docker/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. `lint()` — lint-поверхня; важка реалізація лишається
+ * у js/-хелпері `js/lint.mjs` (main.mjs тонкий — лише re-export).
+ * @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)
+}
+
+export { lint } from './js/lint.mjs'
+
+if (isRunAsCli(import.meta.url)) {
+  // Standalone: bun rules/<id>/main.mjs — повний еквівалент `npx @nitra/cursor check <id>`.
+  process.exitCode = await runRuleCli(import.meta.dirname)
+}

package/rules/efes/docs/index.md

@@ -9,3 +9,4 @@ resource: npm/rules/efes/
 | Файл | Тип |
 |---|---|
 | [fix.mjs](fix.md) | JS Module |
+| [main.mjs](main.md) | JS Module |

package/rules/efes/docs/main.md

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

package/rules/efes/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/feedback/docs/index.md

@@ -9,3 +9,4 @@ resource: npm/rules/feedback/
 | Файл | Тип |
 |---|---|
 | [fix.mjs](fix.md) | JS Module |
+| [main.mjs](main.md) | JS Module |

package/rules/feedback/docs/main.md

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

package/rules/feedback/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/ga/docs/index.md

@@ -9,3 +9,4 @@ resource: npm/rules/ga/
 | Файл | Тип |
 |---|---|
 | [fix.mjs](fix.md) | JS Module |
+| [main.mjs](main.md) | JS Module |