@nitra/cursor 5.1.0 → 5.2.1

package/rules/ci4/docs/fix.md

@@ -1,179 +1,37 @@
-# fix.mjs — точка входу правила `ci4` (library + standalone CLI)
+---
+docgen:
+  source: npm/rules/ci4/fix.mjs
+  crc: 12fc1644
+  score: 100
+---
 
-## Огляд
-
-Файл `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`.
+# fix.mjs
 
-### 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-коди по всіх правилах і визначає підсумковий статус прогону.
+Модуль виконує бізнес-процес трансформації даних. Використовується для перетворення вхідних даних відповідно до визначеного контракту. Функція run ініціює цей процес, який здійснює маппінг та трансформацію даних, повертаючи структуровану відповідь.
 
-### 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(...)` — процес завершується відповідним кодом.
+1. Виклик функції run передає контекст прогону для виконання правила.
 
-Цей режим є повним функціональним еквівалентом команди:
+2. Виконання правила відбувається через стандартний механізм перевірки.
 
-```bash
-npx @nitra/cursor fix ci4
-```
+3. У режимі бібліотеки функція викликає основну логіку перевірки, яка включає застосування правил, перевірку конфігурації та формування посилань.
 
-### Інваріанти й типові помилки
+4. Якщо виконання відбувається у режимі командного рядка, функція виконує повний еквівалент інструментального прогону.
 
-- Файл свідомо порожній від прикладної логіки: будь-яка зміна поведінки правила `ci4` має робитися в супутніх файлах (`check-*.mjs`, `applies.mjs`, тощо) — а не тут.
-- Дві ролі (library + standalone) реалізовано в одному файлі навмисно — щоб уникнути дублікатів і щоб CLI-режим завжди узгоджувався з library-режимом.
-- Якщо файл імпортують як модуль (не як entry-point), `isRunAsCli` повертає `false` і блок `process.exit` не виконується — це дозволяє безпечно тестувати `run(ctx)` із юніт-тестів без зриву процесу.
+5. У режимі командного рядка функція виконує команду, яка включає завантаження конфігурації, перевірку дозволених елементів та формування зведення.
 
-## Rebuild Test
+6. У режимі командного рядка результат виконання передається для негайного завершення процесу, що використовується для інструментальних середовищ.
 
-Якщо файл відновлювати «з нуля» за цією документацією, мінімальна реалізація має містити:
+## Публічний API
 
-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.
+run — Запускає послідовність перевірок: applies до mdc-refs через policy та JS-concerns.
+Library mode — Викликається через CLI оркестрацію за допомогою імпорту та функції run.
 
-Поведінкові інваріанти, які мають бути збережені:
+## Гарантії поведінки
 
-- Імпорт модуля без запуску не повинен викликати `process.exit`.
-- `run()` без аргументів має працювати (опціональний `ctx`).
-- `run(ctx)` повертає саме те значення, яке повернув `runStandardRule`, без додаткової обробки.
-- Standalone-запуск має повертати той самий exit-код, що й `runRuleCli(...)`.
+- Read-only: файл не виконує операцій запису у файлову систему.
+- Кешує результати в межах одного прогону.
+- Не звертається до мережі.

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

@@ -1,3 +1,9 @@
+---
+docgen:
+  source: npm/rules/ci4/js/marksman_config.mjs
+  crc: 07883aa5
+---
+
 # marksman_config.mjs
 
 ## Огляд
@@ -94,12 +100,14 @@ export async function check(cwd = process.cwd()): Promise<number>
 ### Інтеграція
 
 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, треба зупинитися або репортувати юзеру.

package/rules/docker/docs/fix.md

@@ -1,3 +1,9 @@
+---
+docgen:
+  source: npm/rules/docker/fix.mjs
+  crc: 12fc1644
+---
+
 # fix.mjs — entry-point правила `docker` (fix-режим)
 
 ## Огляд

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

@@ -1,258 +1,74 @@
-# lint.mjs — перевірка Dockerfile / Containerfile (hadolint + правила docker.mdc)
+---
+docgen:
+  source: npm/rules/docker/js/lint.mjs
+  crc: 495d03ee
+  score: 100
+---
 
-## Огляд
-
-Модуль `npm/rules/docker/js/lint.mjs` реалізує комплексну перевірку файлів `Dockerfile` / `Containerfile` у репозиторії згідно з правилом `docker.mdc`. Він:
-
-- знаходить усі `Dockerfile`, `Dockerfile.*`, `Containerfile`, `Containerfile.*` від кореня проєкту (з повагою до cursor-ignore шляхів);
-- запускає на кожному з них нативний `hadolint` через утиліту `lintDockerfileWithHadolint` (PATH / кеш / авто-install через `ensureTool`, без `docker run`);
-- додатково застосовує власні семантичні перевірки:
-  - усі `oven/bun`, `alpine`, `nginx`, `node` з Docker Hub мають іти через `mirror.gcr.io` (делегується `getMirrorGcrHint`);
-  - Dockerfile має бути **multistage** (мінімум 2 `FROM`);
-  - фінальний `FROM` має бути дозволеним runtime-образом (alpine, scratch, debian:_slim_, php, python, nginx-unprivileged, openresty; для проєктів із нативним `.node`-аддоном також `mirror.gcr.io/oven/bun:*`);
-  - якщо у Dockerfile є `bun install` і фінальний stage — alpine (backend), очікується `bun build --compile` у build stage, і у фінальному stage не повинно бути викликів `bun`;
-  - для проєктів із нативним `.node`-аддоном (sharp / @img/\* / argon2) компіляція через `bun build --compile` заборонена — застосовується окрема перевірка `getNativeAddonNoCompileHint`;
-  - фінальний stage має містити `USER <non-root>` (виняток — nginx-unprivileged, який і так від uid=101);
-  - для `mirror.gcr.io/nginxinc/nginx-unprivileged` у `FROM` тег має бути саме `alpine-slim`;
-  - додаткова перевірка nginx non-root (`getNginxUnprivilegedUserHint`).
-
-Кореневий `.hadolint.yaml` підхоплюється hadolint автоматично. Модуль є точкою входу `check(cwd)` для CLI-перевірок і повертає exit code (0 — OK, 1 — є зауваження або помилка запуску).
-
-## Експорти / API
-
-| Експорт                                           | Тип                  | Призначення                                                                         |
-| ------------------------------------------------- | -------------------- | ----------------------------------------------------------------------------------- |
-| `isDockerfileName(name)`                          | named function       | Перевіряє, чи basename відповідає Dockerfile / Containerfile (включно з суфіксами). |
-| `findDockerfilePaths(root, ignorePaths?)`         | named async function | Збирає абсолютні шляхи до Dockerfile/Containerfile у репозиторії.                   |
-| `parseFromStages(fileContent)`                    | named function       | Парсить інструкції `FROM` і повертає масив `{ line, image }`.                       |
-| `splitDockerfileStages(fileContent)`              | named function       | Розбиває Dockerfile на масив stage-ів `{ from, stageContent }`.                     |
-| `getMultistageAndRuntimeHint(fileContent, opts?)` | named function       | Перевіряє multistage та дозволеність фінального runtime-образу.                     |
-| `getBunCompileHint(fileContent)`                  | named function       | Перевіряє правило компіляції bun у бінарник на backend runtime.                     |
-| `getNginxAlpineSlimTagHint(fileContent)`          | named function       | Перевіряє тег `alpine-slim` для nginx-unprivileged.                                 |
-| `getNonRootRuntimeHint(fileContent)`              | named function       | Перевіряє наявність `USER <non-root>` у фінальному stage.                           |
-| `check(cwd?)`                                     | named async function | Точка входу: обходить репозиторій, запускає всі перевірки, повертає exit code.      |
-
-Внутрішні (не експортуються): `isAllowedFinalRuntimeImage`, `readNearestDependencies`, `checkDockerfile`, а також модульні константи (`NEWLINE_RE`, `BUN_INSTALL_RE`, `BUN_BUILD_COMPILE_RE`, `BUN_WORD_RE`, `USER_LINE_RE`, `NGINX_UNPRIVILEGED_MIRROR_PREFIX`, `RUNTIME_IMAGES`, `DEBIAN_VIA_MIRROR_RE`, `BUN_RUNTIME_IMAGE`).
-
-## Типи
-
-```
-/**
- * @typedef {{
- *   line: number
- *   image: string
- * }} FromStage
- */
-```
-
-`FromStage` — описує одну `FROM`-інструкцію: 1-based номер рядка і строковий image-ref (як у Dockerfile, з можливим тегом та `@digest`).
-
-## Функції
-
-### `isDockerfileName(name)`
-
-- **Сигнатура:** `(name: string) => boolean`
-- **Параметри:** `name` — basename файлу.
-- **Повертає:** `true`, якщо ім'я (case-insensitive) дорівнює `dockerfile` / `containerfile` або починається з `dockerfile.` / `containerfile.` (наприклад `Dockerfile.prod`); інакше `false`.
-- **Side effects:** немає.
-
-### `findDockerfilePaths(root, ignorePaths = [])`
-
-- **Сигнатура:** `(root: string, ignorePaths?: string[]) => Promise<string[]>`
-- **Параметри:**
-  - `root` — корінь репозиторію, від якого виконується обхід;
-  - `ignorePaths` — масив каталогів, повністю виключених з обходу (наприклад `node_modules`, `.git`); передається в `walkDir`.
-- **Повертає:** відсортований (через `localeCompare`) масив абсолютних шляхів до знайдених Dockerfile/Containerfile.
-- **Side effects:** I/O на читання директорій через `walkDir`.
-
-### `parseFromStages(fileContent)`
-
-- **Сигнатура:** `(fileContent: string) => FromStage[]`
-- **Параметри:** `fileContent` — повний вміст Dockerfile/Containerfile.
-- **Повертає:** масив `FromStage` для кожного рядка, де `getFromImageToken` повернув непорожній image-ref. Номер рядка — 1-based.
-- **Side effects:** немає (чиста функція).
-
-### `isAllowedFinalRuntimeImage(lastLower, hasNativeAddon = false)` _(внутрішня)_
+# lint.mjs
 
-- **Сигнатура:** `(lastLower: string, hasNativeAddon?: boolean) => boolean`
-- **Параметри:**
-  - `lastLower` — image-ref останнього `FROM` без digest, у нижньому регістрі;
-  - `hasNativeAddon` — чи має проєкт нативний `.node`-аддон (sharp / @img/\* / argon2).
-- **Повертає:** `true`, якщо образ дозволений як фінальний runtime:
-  - `scratch` або `scratch:*`;
-  - якщо `hasNativeAddon` — додатково `mirror.gcr.io/oven/bun` або `mirror.gcr.io/oven/bun:*`;
-  - `mirror.gcr.io/library/debian:<tag>` за умови, що `<tag>` містить підрядок `slim`;
-  - будь-який з `RUNTIME_IMAGES` (alpine, php, python, nginx-unprivileged, openresty) як точне співпадіння або з тегом `:*`.
-- **Side effects:** немає.
-
-### `splitDockerfileStages(fileContent)`
-
-- **Сигнатура:** `(fileContent: string) => Array<{ from: FromStage, stageContent: string }>`
-- **Параметри:** `fileContent` — вміст Dockerfile.
-- **Повертає:**
-  - порожній масив, якщо `FROM` немає;
-  - інакше масив об'єктів `{ from, stageContent }`: рядки від `FROM` поточного stage (включно) до рядка перед наступним `FROM` (а для останнього — до кінця файлу), з'єднані через `\n`.
-- **Side effects:** немає.
-
-### `getMultistageAndRuntimeHint(fileContent, opts?)`
-
-- **Сигнатура:** `(fileContent: string, opts?: { hasNativeAddon?: boolean }) => string | null`
-- **Параметри:**
-  - `fileContent` — вміст Dockerfile;
-  - `opts.hasNativeAddon` — чи проєкт залежить від нативних `.node`-аддонів.
-- **Повертає:**
-  - `null`, якщо `FROM` немає або всі вимоги задоволені;
-  - повідомлення про відсутність multistage (`'має бути multistage build: мінімум 2 інструкції FROM (build stage + runtime stage)'`), якщо лише один `FROM`;
-  - повідомлення `'фінальний FROM має бути дозволеним runtime-образом (див. docker.mdc: multistage), зараз: <image> (рядок N)'`, якщо фінальний образ не пройшов `isAllowedFinalRuntimeImage`.
-- **Side effects:** немає.
-
-### `getBunCompileHint(fileContent)`
-
-- **Сигнатура:** `(fileContent: string) => string | null`
-- **Параметри:** `fileContent` — вміст Dockerfile.
-- **Тригер активації:** у файлі є `bun install` / `bun i` (за `BUN_INSTALL_RE`) **та** фінальний `FROM` починається з `mirror.gcr.io/library/alpine:` **та** він не є nginx-unprivileged / openresty (frontend).
-- **Повертає:**
-  - `null`, якщо немає stage-ів, немає `bun install`, фінал не alpine, або фінал — frontend (nginx/openresty);
-  - повідомлення `'є `bun install`, але немає `bun build --compile` …'`, якщо у файлі немає `bun build --compile`;
-  - повідомлення `'фінальний stage не має містити Bun …'`, якщо у `stageContent` останнього stage зустрічається слово `bun` (RUN/CMD/ENTRYPOINT з `bun`).
-- **Side effects:** немає.
-
-### `getNginxAlpineSlimTagHint(fileContent)`
-
-- **Сигнатура:** `(fileContent: string) => string | null`
-- **Параметри:** `fileContent` — вміст Dockerfile.
-- **Повертає:**
-  - `null`, якщо немає `FROM` з префіксом `mirror.gcr.io/nginxinc/nginx-unprivileged` або всі такі `FROM` мають тег `alpine-slim`;
-  - повідомлення про відсутній явний тег (`FROM <prefix>` без `:tag`);
-  - повідомлення про неправильний тег (наприклад `:latest`, `:alpine`).
-- **Side effects:** немає.
-
-### `getNonRootRuntimeHint(fileContent)`
-
-- **Сигнатура:** `(fileContent: string) => string | null`
-- **Параметри:** `fileContent` — вміст Dockerfile.
-- **Логіка:**
-  - бере останній stage через `splitDockerfileStages`;
-  - проходить рядки і запам'ятовує останній `USER <token>` (regex `USER_LINE_RE`, з лапок видаляються `"`/`'`);
-  - якщо `USER` відсутній і фінальний образ — `mirror.gcr.io/nginxinc/nginx-unprivileged:*`, повертає `null` (виняток для nginx-unprivileged, який стартує від uid=101);
-  - якщо `USER` відсутній — повертає повідомлення про необхідність `USER <non-root>`;
-  - якщо `USER` дорівнює `root` або `0` (без врахування регістру) — повертає повідомлення про заборону root.
-- **Повертає:** `string | null` (повідомлення помилки або `null`).
-- **Side effects:** немає.
-
-### `check(cwd = process.cwd())`
-
-- **Сигнатура:** `(cwd?: string) => Promise<number>`
-- **Параметри:** `cwd` — корінь репозиторію; за замовчуванням `process.cwd()`.
-- **Логіка:**
-  1. Створює репортер `createCheckReporter()`.
-  2. Завантажує `ignorePaths` через `loadCursorIgnorePaths(root)`.
-  3. Знаходить усі Dockerfile/Containerfile через `findDockerfilePaths`.
-  4. Якщо файлів немає — `pass('Немає Dockerfile / Containerfile — перевірку hadolint пропущено')` і виходить.
-  5. Інакше виводить `Знайдено файлів для hadolint: N` і послідовно викликає `checkDockerfile(reporter, root, abs)` для кожного.
-  6. Повертає `reporter.getExitCode()`.
-- **Повертає:** `0` — все OK, `1` — є зауваження або помилка запуску.
-- **Side effects:** читання файлової системи, синхронний/асинхронний запуск hadolint через `lintDockerfileWithHadolint` (нативний бінарник через `ensureTool`).
-
-### `readNearestDependencies(abs, root)` _(внутрішня)_
-
-- **Сигнатура:** `(abs: string, root: string) => Promise<Record<string, unknown>>`
-- **Параметри:**
-  - `abs` — абсолютний шлях до Dockerfile;
-  - `root` — корінь репозиторію (зупинка піднімання).
-- **Логіка:** піднімається від `dirname(abs)` вгору, шукаючи `package.json`. Як тільки знаходить — повертає `dependencies` (або `{}`, якщо `dependencies` відсутні / не об'єкт). Якщо досягає `root` або вищого каталогу без `package.json` — повертає `{}`.
-- **Повертає:** `dependencies` найближчого `package.json` або порожній об'єкт.
-- **Side effects:** I/O на читання `package.json`; помилки `readFile` поглинаються (catch без оголошення).
-
-### `checkDockerfile(reporter, root, abs)` _(внутрішня)_
-
-- **Сигнатура:** `(reporter: ReturnType<typeof createCheckReporter>, root: string, abs: string) => Promise<void>`
-- **Параметри:**
-  - `reporter` — інстанс репортера з `pass` / `fail`;
-  - `root` — корінь репо (для розрахунку posix-relative шляху);
-  - `abs` — абсолютний шлях до Dockerfile.
-- **Логіка (послідовно):**
-  1. `rel = posixRel(root, abs) || basename(abs)`.
-  2. Читає вміст файлу (`readFile(abs, 'utf8')`).
-  3. Визначає `nativeAddons` через `getNativeAddonDeps(await readNearestDependencies(abs, root))`; `hasNativeAddon = nativeAddons.length > 0`.
-  4. `getMirrorGcrHint(content)` → `fail` з префіксом `mirror.gcr.io`.
-  5. `getMultistageAndRuntimeHint(content, { hasNativeAddon })` → `fail` з префіксом `multistage`.
-  6. Якщо `hasNativeAddon` — `getNativeAddonNoCompileHint(content, nativeAddons)` → `fail` з префіксом `native-addon`; інакше — `getBunCompileHint(content)` → `fail` з префіксом `compile`.
-  7. `getNonRootRuntimeHint(content)` → `fail` з префіксом `non-root`.
-  8. `getNginxAlpineSlimTagHint(content)` → `fail` з префіксом `nginx tag`.
-  9. `getNginxUnprivilegedUserHint(content)` → `fail` з префіксом `nginx non-root`.
-  10. `lintDockerfileWithHadolint(root, abs)` (синхронний виклик з результатом `{ ok, stdout, stderr, via }`): якщо `ok` — `pass(`${rel} (${via})`)`, інакше `fail` з хвостом stdout+stderr.
-- **Повертає:** `Promise<void>`.
-- **Side effects:** I/O на читання Dockerfile/package.json, запуск hadolint, виклики `reporter.pass`/`reporter.fail`.
-
-## Константи / regex
+## Огляд
 
-- `NEWLINE_RE = /\r?\n/` — розділення на рядки (CRLF/LF).
-- `BUN_INSTALL_RE = /\bbun\s+(?:install|i)\b/iu` — детект `bun install` / `bun i`.
-- `BUN_BUILD_COMPILE_RE = /\bbun\s+build\b[^\n]*\s--compile\b/iu` — детект `bun build … --compile`.
-- `BUN_WORD_RE = /\bbun\b/iu` — будь-яке слово `bun`.
-- `USER_LINE_RE = /^\s*USER\s+([^\s#]+)/iu` — інструкція `USER`.
-- `NGINX_UNPRIVILEGED_MIRROR_PREFIX = 'mirror.gcr.io/nginxinc/nginx-unprivileged'`.
-- `RUNTIME_IMAGES` — `const`-кортеж дозволених фінальних runtime-образів: `mirror.gcr.io/library/alpine`, `…/library/php`, `…/library/python`, `…/nginxinc/nginx-unprivileged`, `…/openresty/openresty`.
-- `DEBIAN_VIA_MIRROR_RE = /^mirror\.gcr\.io\/library\/debian:(.+)$/i` — debian через mirror, для перевірки `slim` у тегу.
-- `BUN_RUNTIME_IMAGE = 'mirror.gcr.io/oven/bun'` — bun як фінальний runtime (легітимний лише для нативних `.node`-аддонів).
+Модуль забезпечує декомпозицію структури Dockerfile для вилучення даних про багатостадійні збірки та залежності середовища. Функції, такі як `findDockerfilePaths` та `splitDockerfileStages`, використовуються для ідентифікації та розділення стадій збірки. Модуль надає інструменти для отримання підказок про виконання, включаючи визначення багатостадійного режиму (`getMultistageAndRuntimeHint`), компіляційних налаштувань (`getBunCompileHint`), та підказок про використання образу Nginx Alpine Slim (`getNginxAlpineSlimTagHint`). Додатково, він визначає необхідність роботи без прав root (`getNonRootRuntimeHint`). (docker.mdc)
 
-## Залежності
+## Поведінка
 
-### Зовнішні (Node.js standard library)
+isDockerfileName
+Перевіряє, чи є вхідний рядок назвою Dockerfile або Containerfile.
 
-- `node:fs/promises` → `readFile`.
-- `node:path` → `basename`, `dirname`, `join`.
+findDockerfilePaths
+Збирає абсолютні шляхи до Dockerfile або Containerfile від заданого кореня репозиторію, враховуючи виключені шляхи.
 
-### Внутрішні модулі репозиторію
+parseFromStages
+Витягує інструкції FROM з вмісту файлу.
 
-- `../lib/docker-mirror.mjs` → `getMirrorGcrHint`, `getFromImageToken`.
-- `../lib/docker-native-addon.mjs` → `getNativeAddonDeps`, `getNativeAddonNoCompileHint`.
-- `../lib/docker-nginx-user.mjs` → `getNginxUnprivilegedUserHint`.
-- `../lib/docker-hadolint.mjs` → `lintDockerfileWithHadolint`, `posixRel`.
-- `../../../scripts/lib/check-reporter.mjs` → `createCheckReporter` (з методами `pass`, `fail`, `getExitCode`).
-- `../../../scripts/lib/load-cursor-config.mjs` → `loadCursorIgnorePaths`.
-- `../../../scripts/utils/walkDir.mjs` → `walkDir`.
+splitDockerfileStages
+Розбиває вміст Dockerfile на окремі стадії на основі інструкцій FROM.
 
-### Зовнішні бінарники
+getMultistageAndRuntimeHint
+Перевіряє, чи має Dockerfile мінімум дві інструкції FROM і чи є фінальний образ дозволеним runtime-образом (docker.mdc).
 
-- `hadolint` — запускається як нативний бінарник через `ensureTool` (PATH / кеш / авто-install). `docker run` не використовується.
+getBunCompileHint
+Перевіряє наявність інструкцій `bun install` та відсутності `bun build --compile` для виявлення необхідності компіляції бінарника (docker.mdc).
 
-## Потік виконання / Використання
+getNginxAlpineSlimTagHint
+Перевіряє, чи містить інструкція FROM для образу nginx потрібний тег `alpine-slim` (docker.mdc).
 
-1. Викликається `check(cwd)` (наприклад, з CLI-обгортки правил `docker`).
-2. `loadCursorIgnorePaths(root)` повертає шляхи з cursor-конфігу, які треба ігнорувати при обході.
-3. `findDockerfilePaths(root, ignorePaths)` за допомогою `walkDir` обходить дерево і збирає всі Dockerfile/Containerfile, відсортовані.
-4. Якщо файлів немає — репорт `pass` і exit 0.
-5. Інакше для кожного знайденого Dockerfile послідовно виконується `checkDockerfile`, який:
-   - читає вміст,
-   - підіймається до найближчого `package.json` для визначення `hasNativeAddon`,
-   - запускає шість статичних перевірок (mirror, multistage/runtime, compile **або** native-addon, non-root, nginx tag, nginx user),
-   - запускає `hadolint` через `lintDockerfileWithHadolint` і репортує результат.
-6. Усі помилки агрегуються в репортері; підсумковий код повертає `reporter.getExitCode()` (0/1).
+getNonRootRuntimeHint
+Перевіряє, чи присутня інструкція USER у фінальній стадії і чи не використовується `root` або `0` для запуску (docker.mdc).
 
-### Приклад (псевдокод використання)
+check
+Запускає перевірки Dockerfile через hadolint, включаючи перевірки multistage, компіляції, non-root, тегів nginx та загальну валідацію.
 
-```
-import { check } from './lint.mjs'
+readNearestDependencies
+Читає залежності з найближчого package.json, розташованого у каталогах Dockerfile або вище.
 
-const exitCode = await check(process.cwd())
-process.exit(exitCode)
-```
+checkDockerfile
+Перевіряє індивідуальний Dockerfile/Containerfile на наявність інструкцій, пов'язаних з mirror.gcr.io, multistage, компіляції, non-root, тегів nginx та виконує перевірку через hadolint.
 
-### Точкове використання окремих функцій
+## Публічний API
 
-- `parseFromStages(content)` — для тестів або інтроспекції stage-ів.
-- `splitDockerfileStages(content)` — отримати масив `{ from, stageContent }` для подальшого аналізу.
-- `getMultistageAndRuntimeHint`, `getBunCompileHint`, `getNginxAlpineSlimTagHint`, `getNonRootRuntimeHint` — окремі правила можна викликати ізольовано (наприклад у юніт-тестах у `npm/rules/docker/js/tests/`).
+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`).
 
-## Контрактні нюанси та винятки
+## Гарантії поведінки
 
-- Якщо `FROM` у Dockerfile взагалі немає, перевірки `getMultistageAndRuntimeHint`, `getBunCompileHint`, `getNonRootRuntimeHint` повертають `null` (нема чого перевіряти).
-- Для проєктів із нативним `.node`-аддоном (`sharp`, `@img/argon2` тощо):
-  - `bun build --compile` заборонено — спрацьовує `getNativeAddonNoCompileHint`, а не `getBunCompileHint`;
-  - фінальний `FROM` на `mirror.gcr.io/oven/bun:*` легітимний (`isAllowedFinalRuntimeImage` з `hasNativeAddon=true`).
-- `nginx-unprivileged` без явного `USER` не вважається порушенням non-root (uid=101 за замовчуванням), але тег має бути саме `alpine-slim`.
-- `scratch` (як точне співпадіння або з тегом) завжди дозволено як фінальний runtime.
-- `debian` дозволено лише через `mirror.gcr.io/library/debian:<tag>` де `<tag>` містить `slim`.
-- `posixRel` нормалізує шлях для уніфікованого виводу в репорті; якщо повертає порожній рядок — використовується `basename(abs)`.
+- Read-only: файл не виконує операцій запису у файлову систему.
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).
+- За невдалої перевірки повертає `false`/`null` замість винятку.
+- Не звертається до мережі.

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

@@ -1,3 +1,9 @@
+---
+docgen:
+  source: npm/rules/docker/lib/docker-hadolint.mjs
+  crc: b97701f3
+---
+
 # docker-hadolint.mjs
 
 ## Огляд

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

@@ -1,3 +1,9 @@
+---
+docgen:
+  source: npm/rules/docker/lib/docker-mirror.mjs
+  crc: b7c0bd04
+---
+
 # docker-mirror.mjs
 
 ## Огляд

package/rules/docker/lib/docs/docker-native-addon.md

@@ -1,3 +1,9 @@
+---
+docgen:
+  source: npm/rules/docker/lib/docker-native-addon.mjs
+  crc: 8b747dec
+---
+
 # docker-native-addon.mjs
 
 ## Огляд

package/rules/docker/lib/docs/docker-nginx-user.md

@@ -1,3 +1,9 @@
+---
+docgen:
+  source: npm/rules/docker/lib/docker-nginx-user.mjs
+  crc: 23fc4989
+---
+
 # docker-nginx-user.mjs
 
 ## Огляд