@nitra/cursor 12.6.1 → 12.8.0

package/rules/doc-files/js/docs/docgen-gen.md

@@ -3,42 +3,31 @@ type: JS Module
 title: docgen-gen.mjs
 resource: npm/rules/doc-files/js/docgen-gen.mjs
 docgen:
-  crc: 7674d2b2
+  crc: 059d7d6e
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 100
 ---
 
-Огляд
-Публічні функції виконують операції з текстом та оцінками. Вони включають виділення коду, вставлення інформації та генерацію документів на основі визначених параметрів.
+## Огляд
 
-## Поведінка
-
-splitProtected
-Вибирає та видаляє код-фенс-обгортку з секції
-
-insertProtected
-Вставляє захищений блок Призначення після заголовка Огляд
+Модуль забезпечує повний цикл роботи з документами: відокремлює захищений блок за допомогою `splitProtected`, вставляє його у визначене місце за допомогою `insertProtected`, генерує повний Markdown-документ через `generateDoc` (з використанням `DEFAULT_LOCAL_MODEL`), а також оцінює якість документа за допомогою `scoreDoc`. Кешування застосовується протягом прогону. (abie.mdc)
 
-scoreDoc
-Перевіряє вихід проти фактів і повертає оцінку та список проблем
-
-DEFAULT_LOCAL_MODEL
-Повертає дефолтну модель для роботи
+## Поведінка
 
-generateDoc
-Генерує документ з детермінованою оцінкою та метаданими
+splitProtected відокремлює захищений блок Призначення від основного документа.
+insertProtected вставляє захищений блок Призначення у фіксовану позицію після заголовка документа.
+scoreDoc оцінює якість згенерованого документа за заданими критеріями.
+DEFAULT_LOCAL_MODEL визначає модель, яка використовується для генерації документа.
+generateDoc генерує повний Markdown-документ з опису файлу, застосовуючи оцінку та можливий ретрай.
 
 ## Публічний API
 
-splitProtected — Відокремлює захищену секцію `## Призначення` (Варіант B). Межа — наступний `## ` і `###` не обриває блок. (abie.mdc)
-insertProtected — Вставляє захищений блок `## Призначення` одразу після H1 (фіксована позиція). (abie.mdc)
-scoreDoc — Stage 2.5 — Детермінований скоринг (0 токенів): перевіряє вихід проти фактів. (abie.mdc)
-DEFAULT_LOCAL_MODEL — Дефолтна модель: N_CURSOR_DOCGEN_MODEL → resolveModel → omlx напряму. Останній fallback гарантує локальний виклик без змін середовища (через pi CLI той самий локальний виклик виміряно повільніший на ~46%). (abie.mdc)
-generateDoc — Головний API: файл → md-дока з det-оцінкою. (abie.mdc)
+splitProtected — Розділяє захищений розділ `## Призначення` (Варіант B), використовуючи наступний заголовок рівня H2 або H3 як межу.
+insertProtected — Розміщує захищений блок `## Призначення` безпосередньо після основного заголовка (H1).
+scoreDoc — Виконує детерміновану оцінку (Stage 2.5), порівнюючи вихідні дані з фактичною інформацією.
+DEFAULT_LOCAL_MODEL — Визначає модель для генерації документа, використовуючи мінімальну локальну модель. Якщо модель не задана, процес зупиняється з помилкою.
+generateDoc — Основна функція, яка перетворює вхідний файл у Markdown-документ з оцінкою достовірності.
 
 ## Гарантії поведінки
 
-- Read-only: файл не виконує операцій запису у файлову систему.
-- Перехоплює помилки і не пропускає винятків назовні (fail-safe).
-- За невдачі повертає значення помилки (`false`/`null`/`Err`) замість генерування винятку чи паніки.
 - Кешує результати в межах одного прогону.
-- Не звертається до мережі.

package/rules/doc-files/js/docs/docgen-judge-measure.md

@@ -3,26 +3,28 @@ type: JS Module
 title: docgen-judge-measure.mjs
 resource: npm/rules/doc-files/js/docgen-judge-measure.mjs
 docgen:
-  crc: e6e19732
+  crc: 86b3120f
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 100
 ---
 
-Файл зчитує список файлів для аналізу, спираючись на конфігурацію `report.json`. Для кожного файлу генерується технічна документація за допомогою локальної моделі. Після генерації документація оцінюється хмарною моделлю. Результати оцінки кешуються у межах прогону, а потім збираються у звіт. Звіт зберігається у `report.json` та виводиться у консоль.
+## Огляд
+
+Модуль обробляє файли, витягуючи їхній зміст для генерації документації. Він порівнює цю документацію з оцінками сильної модільної системи. Під час роботи відбувається кешування у межах прогону. Модуль збирає метрики якості згенерованої документації та зберігає фінальний звіт у `report.json`, який спирається на конфігурації, визначені в `report.json`.
 
 ## Поведінка
 
-1. Зчитує список файлів для аналізу з командного рядка.
+1. Зчитує список файлів для аналізу з аргументів командного рядка.
 2. Для кожного файлу зчитує його вміст.
-3. Генерує документацію для файлу, використовуючи локальну модель. Результат кешується за хешем вмісту джерела.
-4. Якщо генерація документації неможлива або не пройшла встановлений поріг якості, фіксує це як помилку або непідтримуваний файл.
-5. Якщо документація пройшла поріг якості, вона передається для оцінки.
-6. Оцінює згенеровану документацію за допомогою потужної хмарної моделі. Результат оцінки кешується за хешем вмісту джерела та документації.
-7. Якщо оцінка неможлива, фіксує помилку оцінки.
-8. Збирає результати для всіх файлів.
-9. Обчислює звіт, включаючи загальну кількість файлів, кількість успішно згенерованих та оцінених, а також відсоток хибнопозитивних результатів (false-positive rate).
-10. Зберігає повний звіт у файл `report.json` у каталозі кешу.
-11. Виводить консольний звіт з ключовими показниками.
+3. Генерує документацію для файлу, використовуючи кеш за вмістом джерела.
+4. Якщо документація згенерована, перевіряє її якість за встановленим порогом.
+5. Якщо якість документації відповідає порогу, передає вміст джерела та згенеровану документацію для оцінки сильною моделлю.
+6. Оцінювач повертає вердикт (точний, загальний, неточний) з обґрунтуванням.
+7. Зберігає результати для кожного файлу.
+8. Агрегує результати: підраховує загальну кількість файлів, успішно згенерованих, пройшли перевірку, а також розподіл вердиктів серед тих, що пройшли перевірку.
+9. Формує звіт, який включає конфігурацію, підрахунки та відсотки помилкових спрацьовувань.
+10. Зберігає фінальний звіт у файл `report.json` у каталозі кешу.
+11. Виводить консольний звіт про результати вимірювання.
 
 ## Гарантії поведінки
 

package/rules/doc-files/js/docs/docgen-scan.md

@@ -3,50 +3,50 @@ type: JS Module
 title: docgen-scan.mjs
 resource: npm/rules/doc-files/js/docgen-scan.mjs
 docgen:
-  crc: 4c17838f
+  crc: f01465d8
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 100
 ---
 
-isSourceFile перевіряє, чи є файл кодовим джерелом.
-docPathForSource обчислює шлях md-документа для кодового файлу.
-isDocCandidate перевіряє, чи підлягає файл документуванню.
-describeFile описує кодовий файл, включаючи шлях доки та стан застарілості.
-scanForDocFiles рекурсивно обходить дерево, повертаючи кандидати з інформацією про старілість.
-resolveRoot парсить аргументи, щоб визначити абсолютний корінь.
-runDocFilesScanCli сканує дерево і друкує JSON-масив усіх кодових файлів зі станом застарілості.
-runDocFilesCheckCli детектує застарілість для хук'ів, гейтів або інших режимів, повертаючи код виходу.
+## Огляд
+
+Модуль аналізує кодову базу та пов'язану з нею документацію. Він визначає, які файли є джерелами за допомогою `isSourceFile` та знаходить відповідні шляхи документації за допомогою `docPathForSource`. Модуль перевіряє, чи не залишилися без зв'язку (сиротами) документи, використовуючи `scanOrphanedDocs`, та сканує файли документації за допомогою `scanForDocFiles`. Для роботи з кореневими каталогами використовується `resolveRoot`. Усі операції виконуються з механізмом перехоплення помилок (fail-safe), при цьому при певних збоях повертається `null` замість викидання винятків.
 
 ## Поведінка
 
-isSourceFile Обчислює, чи є файл кодовим джерелом.
-docPathForSource Обчислює шлях md-документа для кодового файлу.
-isDocCandidate Перевіряє, чи підлягає файл документуванню.
-describeFile Описує кодовий файл, включаючи шлях доки та стан застарілості.
-scanForDocFiles Рекурсивно обходить дерево, повертаючи кандидати з інформацією про старілість.
-resolveRoot Парсить аргументи, щоб визначити абсолютний корінь.
-runDocFilesScanCli Сканує дерево і друкує JSON-масив усіх кодових файлів зі станом застарілості.
-runDocFilesCheckCli Детектує застарілість для хук'ів, гейтів або інших режимів, повертаючи код виходу.
+isSourceFile визначає, чи є ім'я файлу кодовим джерелом для документування.
+docPathForSource обчислює шлях до відповідного MD-документа для заданого кодового файлу.
+isDocCandidate визначає, чи підлягає певний файл документуванню, враховуючи розширення, статус тесту та ігнорування.
+describeFile описує кодовий файл, надаючи його шлях, шлях до документації та стан застарілості.
+scanOrphanedDocs знаходить MD-документи, які посилаються на кодові файли, що більше не існують.
+scanForDocFiles рекурсивно обходить дерево і повертає список кодових файлів із їхнім станом застарілості, відфільтрований за ігноруванням Git.
+resolveRoot парсить аргументи для визначення абсолютного кореня обходу, використовуючи поточну робочу директорію за замовчуванням.
+runDocFilesScanCli сканує дерево і друкує JSON-масив усіх кодових файлів зі станом застарілості.
+runDocFilesCheckCli виконує перевірку застарілості, підтримуючи режими для перевірки одного файлу, Git-гейту або звітів про знижену якість.
 
 ## Публічний API
 
-isSourceFile — перевіряє, чи є файл коду для документування.
-docPathForSource — обчислює шлях до документа для кодового файлу, розміщуючи його в теці `docs/` поруч із джерелом. Якщо шлях відносний, документ також відносний; якщо абсолютний, документ залишається абсолютним.
-isDocCandidate — визначає, чи підлягає кодовий файл документуванню: має правильне розширення, не є тестом, не знаходиться в ігнорованому списку, і не є кореневим системним документуванням.
-describeFile — надає опис кодового файлу: шлях до джерела, шлях до документа та стан застарілості за CRC.
-scanForDocFiles — рекурсивно переглядає дерево від заданого кореня і повертає кодові файли разом зі станом застарілості.
-resolveRoot — парсить аргумент `--root <dir>` з командного рядка; за замовчуванням використовує поточну робочу директорію.
-runDocFilesScanCli — сканує дерево і виводить JSON-масив усіх кодових файлів із зазначенням їхнього стану застарілості.
-runDocFilesCheckCli — виконує перевірку застарілості для хуків та командного рядка через інструмент `doc-files check`.
-Режими — це способи виконання:
---hook — бере шлях до файлу з вводу JSON і перевіряє один файл.
---git — перевіряє різницю в Git (`git diff --name-only HEAD`) з урахуванням порогу `--max` (за замовчуванням 50); якщо застарілості більше, не блокує (виходить з кодом 0 з попередженням).
---degraded — генерує інформаційний звіт про документи, які мають оцінку нижче встановленого порогу (виходить з кодом 0).
-<paths…> — використовується для визначення явних шляхів до джерел.
-Exit 2 — повертається, якщо знайдено застарілі дані; повертається 0, якщо дані свіжі або пройдено перевищення порогу.
+isSourceFile — визначає, чи є файл кодовим джерелом для створення документації.
+docPathForSource — визначає шлях до відповідного MD-документа, розміщений у теці `docs/` відносно коду.
+isDocCandidate — вирішує, чи повинен кодовий файл бути документований: має правильне розширення, не є тестом, не ігнорується та не є системним документом.
+describeFile — надає опис кодового файлу, включаючи його шлях, шлях до документації та статус застарілості.
+scanOrphanedDocs — шукає документи, які посилаються на кодові файли, що більше не існують, перевіряючи лише згенеровані файли.
+scanForDocFiles — рекурсивно збирає всі кодові файли з дерева, визначаючи їхній статус застарілості, і відсіюючи ті, що ігноруються через `.gitignore`.
+resolveRoot — встановлює кореневу директорію для сканування, використовуючи аргумент командного рядка або поточну робочу директорію.
+runDocFilesScanCli — сканує дерево та виводить JSON-масив усіх кодових файлів зі статусом застарілості, дозволяючи фільтрувати лише застарілі або всі файли.
+runDocFilesCheckCli — виконує перевірку застарілості для використання у хуках та командному інтерфейсі.
+
+Режими:
+--hook — перевіряє один файл, отриманий з JSON через стандартний ввід.
+--git — порівнює файли у `git diff` та блокує процес, якщо знайдено більше за встановлений поріг застарілих файлів.
+--degraded — виводить звіт про документи з низьким показником якості.
+<paths…> — обробляє лише вказані шляхи-джерела.
+
+Вихідний код 2 — вказує на знаходження застарілих файлів (для блокування хука).
+Вихідний код 0 — вказує на відсутність застарілих файлів або проходження перевірки згідно з порогом.
 
 ## Гарантії поведінки
 
-- Read-only: файл не виконує операцій запису у файлову систему.
+- Read-only: не виконує операцій запису (ФС/БД).
 - Перехоплює помилки і не пропускає винятків назовні (fail-safe).
-- За невдачі повертає значення помилки (`false`/`null`/`Err`) замість генерування винятку чи паніки.
-- Не звертається до мережі.
+- За певних помилок повертає порожнє значення (напр. `null`) замість винятку.

package/rules/doc-files/js/docs/index.md

@@ -6,19 +6,20 @@ resource: npm/rules/doc-files/js/
 
 # npm/rules/doc-files/js
 
-| Файл | Тип |
-|---|---|
-| [docgen-crc.mjs](docgen-crc.md) | JS Module |
+| Файл                                                    | Тип       |
+| ------------------------------------------------------- | --------- |
+| [docgen-crc.mjs](docgen-crc.md)                         | JS Module |
 | [docgen-extract-anchors.mjs](docgen-extract-anchors.md) | JS Module |
-| [docgen-extract.mjs](docgen-extract.md) | JS Module |
-| [docgen-files-batch.mjs](docgen-files-batch.md) | JS Module |
-| [docgen-gen.mjs](docgen-gen.md) | JS Module |
-| [docgen-ignore.mjs](docgen-ignore.md) | JS Module |
-| [docgen-judge-measure.mjs](docgen-judge-measure.md) | JS Module |
-| [docgen-judge.mjs](docgen-judge.md) | JS Module |
-| [docgen-prompts.mjs](docgen-prompts.md) | JS Module |
-| [docgen-scan.mjs](docgen-scan.md) | JS Module |
-| [lint.mjs](lint.md) | JS Module |
-| [units-js.mjs](units-js.md) | JS Module |
-| [units-rs.mjs](units-rs.md) | JS Module |
-| [units.mjs](units.md) | JS Module |
+| [docgen-extract.mjs](docgen-extract.md)                 | JS Module |
+| [docgen-files-batch.mjs](docgen-files-batch.md)         | JS Module |
+| [docgen-gen.mjs](docgen-gen.md)                         | JS Module |
+| [docgen-ignore.mjs](docgen-ignore.md)                   | JS Module |
+| [docgen-judge-measure.mjs](docgen-judge-measure.md)     | JS Module |
+| [docgen-judge.mjs](docgen-judge.md)                     | JS Module |
+| [docgen-prompts.mjs](docgen-prompts.md)                 | JS Module |
+| [docgen-scan.mjs](docgen-scan.md)                       | JS Module |
+| [lint.mjs](lint.md)                                     | JS Module |
+| [run-lint.mjs](run-lint.md)                             | JS Module |
+| [units-js.mjs](units-js.md)                             | JS Module |
+| [units-rs.mjs](units-rs.md)                             | JS Module |
+| [units.mjs](units.md)                                   | JS Module |

package/rules/doc-files/js/docs/run-lint.md

@@ -0,0 +1,27 @@
+---
+type: JS Module
+title: run-lint.mjs
+resource: npm/rules/doc-files/js/run-lint.mjs
+docgen:
+  crc: ba329b37
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 80
+---
+
+## Огляд
+
+Цей модуль надає CLI-обгортку для канонічного `lint-doc-files` (doc-files.mdc): детермінованого детектора застарілості файлових док (`<dir>/docs/<stem>.md`). При відсутності прапорців або при вказанні шляхів (`[paths…]`) виконується повний або точковий детекст застарілості. Якщо знайдено застарілі файли, повертається код виходу 1. Можливі режими: `--missing-only` звужує перевірку до відсутніх файлів. Прапорець `--json` виводить JSON-лістинг усіх кандидатів. Режими `--hook`, `--git` та `--degraded` делегують перевірку через `runDocFilesCheckCli` (hook-протокол: exit 2/0). Повний прогін здійснюється через `runStandardLint` (ключ `lint-doc-files`), тоді як хук/git/degraded форми використовують канон scripts.mdc, не генеруючи логів. Поведінка описується у (doc-files.mdc).
+
+## Поведінка
+
+runLintDocFilesSteps виконує повний або точковий детект застарілості файлової документації (doc-files.mdc), повертаючи код виходу 1, якщо знайдено застарілі файли, або 0, якщо всі актуальні.
+runLintDocFilesCli керує викликом лінтера doc-files.mdc: виконує повний/точковий детект, якщо не вказано `--json`, або повертає JSON-лістинг кандидатів, якщо вказано `--json`, або делегує перевірку через протоколи `--hook`, `--git`, `--degraded`.
+
+## Публічний API
+
+runLintDocFilesSteps — Виконує повний або точковий пошук неактуальних (stale) файлів документації. Повертає код виходу 1, якщо знайдено неактуальні файли, і 0, якщо всі файли актуальні.
+runLintDocFilesCli — Виконує перевірку файлів документації через інтерфейс командного рядка. У режимах hook/git/degraded виконує делегацію без логування. З опцією `--json` виконує сканування. В інших режимах виконує повний або точковий пошук, використовуючи логіку `runStandardLint` для ключа `lint-doc-files`.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).

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

@@ -23,8 +23,9 @@ import {
   resolveRoot,
   runDocFilesCheckCli,
   runDocFilesScanCli,
-  scanForDocFiles
-} from '../js/docgen-scan.mjs'
+  scanForDocFiles,
+  scanOrphanedDocs
+} from './docgen-scan.mjs'
 
 /**
  * Нормалізує шлях-кандидат до posix-шляху від кореня (null поза деревом).
@@ -73,15 +74,28 @@ export function runLintDocFilesSteps(argv) {
   let stale = described.filter(f => f.stale)
   if (missingOnly) stale = stale.filter(f => f.reason === 'missing')
 
-  if (stale.length === 0) {
+  // Orphan-детект лише при повному скані (без явних шляхів); точковий — не релевантно
+  const orphans = paths.length === 0 ? scanOrphanedDocs(root) : []
+
+  let exitCode = 0
+  if (stale.length > 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`
+    )
+    exitCode = 1
+  }
+  if (orphans.length > 0) {
+    const list = orphans.map(f => `  - ${f}`).join('\n')
+    console.error(
+      `✗ doc-files: сирітських доків (source видалено) ${orphans.length}:\n${list}\n→ очисти: npx @nitra/cursor fix-doc-files`
+    )
+    exitCode = 1
+  }
+  if (exitCode === 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
+  return exitCode
 }
 
 /**

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/fix.md

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

package/rules/docker/docs/index.md

@@ -6,6 +6,7 @@ resource: npm/rules/docker/
 
 # npm/rules/docker
 
-| Файл | Тип |
-|---|---|
-| [fix.mjs](fix.md) | JS Module |
+| Файл                | Тип       |
+| ------------------- | --------- |
+| [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/index.md

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

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))
+}