@nitra/cursor 3.22.0 → 3.23.0

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

@@ -0,0 +1,247 @@
+# docker-mirror.mjs
+
+## Огляд
+
+Модуль `docker-mirror.mjs` — це частина правила `n-docker` (тека `npm/rules/docker/lib/`) монорепо `n-cursor`. Він реалізує чисту (без I/O, без побічних ефектів) бібліотеку функцій для статичного аналізу директив `FROM` у файлах `Dockerfile` / `Containerfile` та визначає, чи звертається образ до Docker Hub без використання GCR-дзеркала `mirror.gcr.io`.
+
+Призначення:
+
+- Перевірити, що базові образи з обмеженого списку популярних публічних репозиторіїв (`oven/bun`, `library/alpine`, `library/nginx`, `library/node`, `nginxinc/nginx-unprivileged`) тягнуться не напряму з Docker Hub, а через дзеркало `mirror.gcr.io` (зменшує ризики rate limiting Docker Hub та підвищує доступність CI/CD).
+- Виявити порушення й сформувати людиночитане повідомлення з номером рядка та рекомендованим референсом образу.
+
+Модуль свідомо ігнорує приватні реєстри (наприклад, `gcr.io/foo/bar`, `registry.example.com:5000/app`, IP-адреси, `localhost`). Канонічні заміни:
+
+- `oven/bun` → `mirror.gcr.io/oven/bun`
+- `library/alpine` → `mirror.gcr.io/library/alpine`
+- `library/nginx` → `mirror.gcr.io/library/nginx`
+- `library/node` → `mirror.gcr.io/library/node`
+- `nginxinc/nginx-unprivileged` → `mirror.gcr.io/nginxinc/nginx-unprivileged`
+
+Модуль є чистим: жодних звернень до файлової системи, мережі, глобального стану. Усі експортовані функції детерміновані й безпечні для повторного виклику.
+
+## Експорти / API
+
+Файл є ES-модулем (`.mjs`) і експортує чотири іменовані функції; стандартного експорту немає.
+
+| Експорт                     | Тип                                       | Призначення                                                              |
+| --------------------------- | ----------------------------------------- | ------------------------------------------------------------------------ |
+| `getFromImageToken`         | `(line: string) => string \| null`        | Витягує токен образу з рядка `FROM` Dockerfile.                          |
+| `isDockerHubStyleImageRef`  | `(imageToken: string) => boolean`         | Повертає `true`, якщо посилання схоже на Docker Hub.                     |
+| `normalizeHubRepoPath`      | `(imageToken: string) => string`          | Нормалізує шлях репозиторію (без тега/digest) у канонічну форму.         |
+| `getRequiredMirrorGcrImage` | `(imageToken: string) => string \| null`  | Повертає рекомендований `mirror.gcr.io/...`-референс, якщо потрібен.     |
+| `getMirrorGcrHint`          | `(fileContent: string) => string \| null` | Сканує вміст Dockerfile та повертає підказку про порушення (або `null`). |
+
+Внутрішні (не експортовані) допоміжні елементи:
+
+- Константи-регулярки: `FROM_LINE_RE`, `TOKEN_RE`, `MIRROR_GCR_RE`, `IP_LIKE_RE`, `HOST_PORT_RE`, `DOCKER_IO_PREFIX_RE`, `NEWLINE_SPLIT_RE`.
+- Функція `stripFromImageQuotes(t)` — знімає зовнішні одинарні/подвійні лапки з токена.
+- `HUB_REPOS_REQUIRING_MIRROR` — `Set` із п'яти канонічних шляхів репозиторіїв, що підлягають дзеркалу.
+- `EXPECTED_MIRROR` — `Record<string, string>` із зіставленням канонічний шлях → рекомендований `mirror.gcr.io/...` префікс.
+
+## Функції
+
+### `stripFromImageQuotes(t)`
+
+Внутрішня (не експортована) утиліта.
+
+- **Сигнатура:** `(t: string) => string`
+- **Параметри:**
+  - `t` — токен образу, можливо обгорнутий парою `"…"` або `'…'`.
+- **Повертає:** ту саму рядкову форму без зовнішньої пари лапок, якщо довжина ≥ 2 і перший символ — `"` або `'`. Інакше — рядок без змін.
+- **Side effects:** немає (чиста функція).
+- **Особливості:** не валідовує парність лапок (просто зрізає перший і останній символи). Передбачає, що вхід уже виокремлено токенайзером, який сам парує лапки (`TOKEN_RE`).
+
+### `getFromImageToken(line)`
+
+Експортована.
+
+- **Сигнатура:** `(line: string) => string | null`
+- **Параметри:**
+  - `line` — один рядок із Dockerfile.
+- **Повертає:**
+  - Токен образу (без зовнішніх лапок), напр. `node:20-alpine`, `mirror.gcr.io/oven/bun:1.2`, `gcr.io/distroless/static@sha256:…`.
+  - `null`, якщо рядок не директива `FROM` або токен не вдалося виокремити (порожньо, лише прапорці тощо).
+- **Алгоритм:**
+  1. Зрізає inline-коментар: `line.split('#')[0].trim()`.
+  2. Перевіряє, що результат починається з `FROM ` (case-insensitive) через `FROM_LINE_RE`.
+  3. Розбиває залишок на токени за `TOKEN_RE` — регулярка зберігає вміст у лапках як один токен.
+  4. Циклом проходить токени, ігноруючи прапорці:
+     - `--platform=…` — один токен, пропустити.
+     - `--platform` без `=` — пропустити 2 токени (прапорець + значення), або 1, якщо значення відсутнє.
+     - `--` або `AS` (case-insensitive) — припиняє пошук (повертає `null`, якщо токен ще не знайдено).
+     - Інший `--key=value` — пропустити 1 токен.
+     - Інший `--key` — пропустити 1 токен (припускає, що це boolean-прапорець без значення; це може бути неточно для прапорців із наступним значенням, окрім `--platform`).
+     - Перший не-прапорцевий токен — це образ; повертає `stripFromImageQuotes(token)`.
+- **Side effects:** немає.
+- **Особливості:**
+  - Не валідовує синтаксис Dockerfile повністю: підтримує найрозповсюдженіші форми `FROM`.
+  - Не розпізнає неіменованих прапорців із наступним значенням (`--foo bar`) — `bar` буде сприйнято як токен образу. Це компроміс заради простоти; для канонічного Dockerfile `--platform` — єдиний релевантний випадок.
+  - Залишок після образу (наприклад, `AS base`) не повертається.
+
+### `isDockerHubStyleImageRef(imageToken)`
+
+Експортована.
+
+- **Сигнатура:** `(imageToken: string) => boolean`
+- **Параметри:**
+  - `imageToken` — ref образу (як повертає `getFromImageToken`).
+- **Повертає:** `true`, якщо посилання виглядає як pull із Docker Hub; інакше `false`.
+- **Алгоритм:**
+  1. Порожнє/falsy значення → `false`.
+  2. Починається з `mirror.gcr.io/` (за `MIRROR_GCR_RE`) → `false` (це вже дзеркало, не Hub).
+  3. Зрізає `@digest` (`imageToken.split('@')[0]`).
+  4. Якщо немає `/` — це коротке ім'я (`node:20`, `alpine`) → `true`.
+  5. Виокремлює перший сегмент `first = noDigest.split('/')[0]`.
+  6. `first === 'docker.io'` або `first === 'index.docker.io'` → `true`.
+  7. Якщо `first` містить крапку (`.`) — це FQDN чужого реєстру (`gcr.io`, `ghcr.io`, `registry.example.com`) → `false`.
+  8. `first === 'localhost'` або відповідає IP-патерну `^\d+\.\d+` → `false` (приватний/локальний реєстр).
+  9. Містить `:` й відповідає `^\S+:\d+$` (host:port) → `false`.
+  10. Інакше → `true` (типова форма `user/repo` або `org/image:tag`, яку Docker за замовчуванням резолвить через Docker Hub).
+- **Side effects:** немає.
+- **Особливості:** правило "крапка у першому сегменті = чужий реєстр" — Docker-канонічне евристичне правило (Docker CLI використовує його для розрізнення `docker.io/library/foo` від коротких посилань).
+
+### `normalizeHubRepoPath(imageToken)`
+
+Експортована.
+
+- **Сигнатура:** `(imageToken: string) => string`
+- **Параметри:**
+  - `imageToken` — ref образу (передбачається, що це Hub-style, як після `isDockerHubStyleImageRef`).
+- **Повертає:** канонічний шлях репозиторію (lower-case, без тега, без digest, без префіксу `docker.io/`):
+  - `node` → `library/node`
+  - `node:20-alpine` → `library/node`
+  - `docker.io/oven/bun:1.2` → `oven/bun`
+  - `index.docker.io/library/alpine` → `library/alpine`
+  - `oven/bun@sha256:…` → `oven/bun`
+- **Алгоритм:**
+  1. Зрізає `@digest`, переводить у lower-case.
+  2. Зрізає префікс `docker.io/` або `index.docker.io/` (через `DOCKER_IO_PREFIX_RE`).
+  3. Якщо немає `/` — це коротке ім'я: повертає `library/<name>` (де `<name>` — частина до `:`).
+  4. Інакше шукає останній `/` і останній `:`. Якщо `:` йде після `/`, це тег — зрізає від нього й до кінця.
+- **Side effects:** немає.
+- **Особливості:** уважно обробляє port-у-host (`host:5000/foo`) для випадків, коли функцію викликають на не-Hub посиланнях — порт перед `/` зберігається, тільки тег після останнього `/` зрізається. Однак функція передбачена для Hub-посилань і не повинна викликатися на FQDN.
+
+### `getRequiredMirrorGcrImage(imageToken)`
+
+Експортована.
+
+- **Сигнатура:** `(imageToken: string) => string | null`
+- **Параметри:**
+  - `imageToken` — ref після `FROM` (як повертає `getFromImageToken`).
+- **Повертає:**
+  - Рекомендований `mirror.gcr.io/...` шлях (без тега й digest), якщо образ Hub-style і входить до `HUB_REPOS_REQUIRING_MIRROR`.
+  - `null`, якщо: токен порожній; вже використовує `mirror.gcr.io/...`; не Hub-style; нормалізований шлях не входить до списку.
+- **Алгоритм:**
+  1. `!imageToken` → `null`.
+  2. `MIRROR_GCR_RE.test(imageToken)` → `null` (вже на дзеркалі).
+  3. `!isDockerHubStyleImageRef(imageToken)` → `null` (приватний реєстр).
+  4. `norm = normalizeHubRepoPath(imageToken)`.
+  5. Якщо `!HUB_REPOS_REQUIRING_MIRROR.has(norm)` → `null` (інший Hub-образ, правило не застосовується).
+  6. Повертає `EXPECTED_MIRROR[norm]`.
+- **Side effects:** немає.
+
+### `getMirrorGcrHint(fileContent)`
+
+Експортована.
+
+- **Сигнатура:** `(fileContent: string) => string | null`
+- **Параметри:**
+  - `fileContent` — повний вміст Dockerfile/Containerfile (рядки розділені `\n` або `\r\n`).
+- **Повертає:**
+  - Рядок виду `рядок <N>: FROM має тягнути mirror.gcr.io/<repo> (замість <orig-token>)` — для першого знайденого порушення.
+  - `null`, якщо порушень немає.
+- **Алгоритм:**
+  1. Ділить контент на рядки за `NEWLINE_SPLIT_RE` (`/\r?\n/`).
+  2. Ітерує з індексом (`.entries()`); номер рядка у повідомленні — `n + 1` (1-based).
+  3. Для кожного рядка: `image = getFromImageToken(line)`; `expected = getRequiredMirrorGcrImage(image)`.
+  4. Перший рядок, де `expected` істинний (string), формує повідомлення і функція повертається.
+- **Side effects:** немає.
+- **Особливості:**
+  - Зупиняється на першому порушенні (fail-fast). Якщо в одному Dockerfile є кілька `FROM` із порушеннями — повідомлено буде лише про перший.
+  - Текст повідомлення українською (узгоджується з мовою спец-документів проєкту).
+
+## Залежності
+
+- **Зовнішні модулі:** немає (`import`/`require` відсутні).
+- **Внутрішні модулі:** немає; модуль самодостатній.
+- **Глобальні API:** виключно стандартний JavaScript — `RegExp`, `String.prototype` (`split`, `trim`, `match`, `slice`, `toLowerCase`, `replace`, `includes`, `startsWith`, `lastIndexOf`), `Set`, `Array.prototype.entries`.
+- **Runtime:** ESM, працює в Node.js та Bun. Розширення `.mjs` обов'язкове за правилом `n-bun`/`n-js-run`.
+- **JSDoc типи:** використовуються `@type`, `@param`, `@returns` із касти `/** @type {const} */` для іммутабельних літералів — допомагають TypeScript/JSDoc-перевірці й ESLint.
+
+## Потік виконання / Використання
+
+### Типовий сценарій інтеграції
+
+Модуль використовується перевіркою правила `n-docker` (вочевидь, файл `check-*.mjs` у `npm/rules/docker/`), яка:
+
+1. Знаходить усі `Dockerfile` / `Containerfile` у воркспейсі.
+2. Для кожного зчитує вміст і передає в `getMirrorGcrHint(content)`.
+3. Якщо результат — рядок, репортує його як порушення лінтера/правила.
+
+### Програмний приклад
+
+```js
+import { getMirrorGcrHint } from './docker-mirror.mjs'
+
+const dockerfile = `
+# syntax=docker/dockerfile:1
+FROM --platform=linux/amd64 node:20-alpine AS builder
+RUN bun install
+FROM mirror.gcr.io/library/nginx:1.27
+COPY --from=builder /app /usr/share/nginx/html
+`
+
+const hint = getMirrorGcrHint(dockerfile)
+if (hint) {
+  console.error(hint)
+  // → рядок 3: FROM має тягнути mirror.gcr.io/library/node (замість node:20-alpine)
+}
+```
+
+### Гранулярне використання
+
+```js
+import {
+  getFromImageToken,
+  isDockerHubStyleImageRef,
+  normalizeHubRepoPath,
+  getRequiredMirrorGcrImage
+} from './docker-mirror.mjs'
+
+const token = getFromImageToken('FROM --platform=$BUILDPLATFORM oven/bun:1.2 AS bun')
+// → 'oven/bun:1.2'
+
+isDockerHubStyleImageRef(token) // → true
+normalizeHubRepoPath(token) // → 'oven/bun'
+getRequiredMirrorGcrImage(token) // → 'mirror.gcr.io/oven/bun'
+
+getRequiredMirrorGcrImage('gcr.io/foo/bar') // → null (чужий реєстр)
+getRequiredMirrorGcrImage('mirror.gcr.io/library/node') // → null (вже на дзеркалі)
+getRequiredMirrorGcrImage('redis:7') // → null (не в списку)
+```
+
+### Покриті випадки
+
+- `FROM node` — коротке ім'я, рекомендує `mirror.gcr.io/library/node`.
+- `FROM library/alpine:3.19` — Hub з явним `library/`, рекомендує `mirror.gcr.io/library/alpine`.
+- `FROM docker.io/oven/bun:1.2` — Hub з явним хостом, рекомендує `mirror.gcr.io/oven/bun`.
+- `FROM --platform=linux/arm64 nginx AS base` — пропускає прапорці й `AS`.
+- `FROM "node:20"` — знімає лапки.
+- `FROM nginxinc/nginx-unprivileged:1.27` — Hub-style з користувацьким наміспейсом, рекомендує `mirror.gcr.io/nginxinc/nginx-unprivileged`.
+
+### Випадки, що не вважаються порушенням
+
+- `FROM gcr.io/distroless/static` — крапка в першому сегменті → чужий реєстр.
+- `FROM localhost:5000/myapp` — `localhost` + порт → приватний реєстр.
+- `FROM 10.0.0.1/internal/app` — IP-патерн → приватний реєстр.
+- `FROM mirror.gcr.io/library/node:20` — вже використовує дзеркало.
+- `FROM redis:7` — Hub, але не в списку контрольованих репозиторіїв.
+- `FROM scratch` — `scratch` нормалізується до `library/scratch`, але його немає в `HUB_REPOS_REQUIRING_MIRROR`.
+
+### Обмеження й нюанси
+
+- Перевірка зупиняється на першому порушенні в файлі. Якщо потрібно зібрати всі порушення — функцію треба інтегрувати на рівні викликача (наприклад, проходом по `fileContent.split('\n')` із власною агрегацією).
+- Багаторядкові `FROM` із продовженням рядка через `\` не підтримуються (Dockerfile-специфіка така, що `FROM` зазвичай одно-рядковий, але формально це можливо).
+- Інші прапорці з пробільним значенням (наприклад, гіпотетичне `--foo bar`) можуть бути неточно розпарсені — `bar` буде сприйнято як токен образу. Для канонічних Dockerfile цей випадок не реалістичний.
+- Heredoc-форма Dockerfile (`FROM <<EOF`) явно не підтримується.
+- Регістр літерала `FROM` нечутливий (`FROM_LINE_RE` має флаг `i`); літерал `AS` теж нечутливий (порівняння через `.toUpperCase()`); імена реєстрів і репозиторіїв нормалізуються через `.toLowerCase()`.

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

@@ -0,0 +1,170 @@
+# docker-native-addon.mjs
+
+## Огляд
+
+Модуль `docker-native-addon.mjs` — це dep-специфічний чек-модуль правила `docker` для виявлення антипатерну, коли проєкт залежить від нативного `.node`-аддона з динамічним завантаженням біндингу (через динамічний `require`), і одночасно намагається бути запакованим через `bun build --compile` у Dockerfile.
+
+Контекст проблеми:
+
+- Деякі npm-пакети (передусім `sharp`, а також пакети у scope `@img/*`, `argon2`) містять нативний `.node`-аддон, який вантажиться у рантаймі через **динамічний** виклик `require`, наприклад `require(\`@img/sharp-${platform}/sharp.node\`)`. Ім'я модуля формується з підстановки змінних.
+- Компілятор `bun build --compile` виконує статичний трейсинг імпортів і **не** бачить такі динамічні `require`, тож **не вшиває** відповідний нативний біндинг у standalone-бінарник.
+- Результат — рантайм-помилка на кшталт `Could not load the "sharp" module using the linuxmusl-arm64 runtime`. Підтверджено реальними docker-збірками (`bun 1.3.14`, `sharp 0.34.5`) і відтворюється також на `darwin-arm64`, тобто проблема не пов'язана з різницею musl/glibc.
+- Установка системного `apk add vips` **не** лікує проблему: вона дає системний `libvips`, але самого файлу `sharp.node` усе одно бракує.
+
+Канонічне рішення для таких проєктів (за правилом `docker.mdc`, секція «компіляція»): **не** компілювати в standalone-бінарник, а shipити `node_modules` як є й запускати застосунок через `bun <entry>` на базі образу `mirror.gcr.io/oven/bun:alpine`. Це визнаний виняток із загального правила «лише `alpine`/`scratch` у фінальному stage» — тут потрібен саме bun-рантайм.
+
+Це окрема гілка від генеричного compile-правила (`getBunCompileHint` у `../js/lint.mjs`): для проєктів **без** нативних аддонів канон лишається — standalone-бінарник на `alpine`.
+
+Сусідній модуль `./docker-mirror.mjs` слугує взірцем структури dep-специфічного чек-модуля.
+
+## Експорти / API
+
+Модуль експортує два константи (іменовані експорти) і три функції (іменовані експорти):
+
+| Експорт                                                  | Тип                                                               | Призначення                                                                                   |
+| -------------------------------------------------------- | ----------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
+| `NATIVE_ADDON_PACKAGES`                                  | `readonly ['sharp', 'argon2']`                                    | Точні імена відомих нативних аддонів.                                                         |
+| `NATIVE_ADDON_SCOPES`                                    | `readonly ['@img/']`                                              | Scope-префікси, чиї пакети трактуються як нативні аддони.                                     |
+| `isNativeAddonPackage(name)`                             | `(name: string) => boolean`                                       | Чи ім'я npm-пакета є нативним аддоном (точно або за scope-префіксом).                         |
+| `getNativeAddonDeps(dependencies)`                       | `(dependencies: unknown) => string[]`                             | Відсортовані імена нативних аддонів, знайдених у `package.json#dependencies`.                 |
+| `getNativeAddonNoCompileHint(fileContent, nativeAddons)` | `(fileContent: string, nativeAddons: string[]) => string \| null` | Текст hint-помилки, якщо у Dockerfile є `bun build --compile` при наявності нативного аддона. |
+
+Default-експорт відсутній.
+
+## Функції
+
+### `isNativeAddonPackage(name)`
+
+Сигнатура:
+
+```js
+isNativeAddonPackage(name: string): boolean
+```
+
+Параметри:
+
+- `name` — ім'я npm-пакета (рядок). Очікується очищене ім'я ключа з `package.json#dependencies`, наприклад `"sharp"` або `"@img/sharp-linuxmusl-arm64"`.
+
+Повертає:
+
+- `true`, якщо `name` присутній у списку `NATIVE_ADDON_PACKAGES` (точне співпадіння), **або** починається з будь-якого з префіксів `NATIVE_ADDON_SCOPES` (наприклад, `@img/`).
+- `false` в усіх інших випадках.
+
+Алгоритм:
+
+1. Якщо `NATIVE_ADDON_PACKAGES.includes(name)` — повернути `true`. Аргумент `name` кастомним каста `/** @type {never} */` сатисфіє `readonly`-літерал-тип константи.
+2. Інакше повернути результат `NATIVE_ADDON_SCOPES.some(scope => name.startsWith(scope))`.
+
+Side effects: відсутні. Чиста функція.
+
+### `getNativeAddonDeps(dependencies)`
+
+Сигнатура:
+
+```js
+getNativeAddonDeps(dependencies: unknown): string[]
+```
+
+Параметри:
+
+- `dependencies` — значення поля `dependencies` з `package.json`. Тип навмисно `unknown` — функція сама перевіряє форму вхідних даних.
+
+Повертає:
+
+- Відсортований за локалізованим порядком (`String#localeCompare`) масив ключів `dependencies`, відфільтрованих через `isNativeAddonPackage`.
+- Порожній масив `[]`, якщо `dependencies` має невалідну форму (falsy, не об'єкт, або масив), або якщо серед ключів немає нативних аддонів.
+
+Алгоритм:
+
+1. Якщо `!dependencies` (null/undefined/інше falsy), або `typeof dependencies !== 'object'`, або `Array.isArray(dependencies)` — повернути `[]`.
+2. Зібрати ключі через `Object.keys(dependencies)`.
+3. Відфільтрувати через `isNativeAddonPackage`.
+4. Повернути копію, відсортовану через `.toSorted((a, b) => a.localeCompare(b))` (іммутабельне сортування, не мутує вихідний масив ключів).
+
+Side effects: відсутні. Чиста функція; виклик `Object.keys` не мутує вхід.
+
+### `getNativeAddonNoCompileHint(fileContent, nativeAddons)`
+
+Сигнатура:
+
+```js
+getNativeAddonNoCompileHint(fileContent: string, nativeAddons: string[]): string | null
+```
+
+Параметри:
+
+- `fileContent` — повний вміст Dockerfile або Containerfile як рядок.
+- `nativeAddons` — масив імен нативних аддонів, попередньо знайдених у `dependencies` (результат `getNativeAddonDeps`).
+
+Повертає:
+
+- Рядок з повідомленням-підказкою про порушення, якщо тригер спрацював.
+- `null`, якщо порушень не виявлено.
+
+Тригер (умови, що мають виконатись усі одночасно):
+
+1. `nativeAddons` — масив (`Array.isArray`) і непорожній.
+2. У `fileContent` знайдено патерн `bun build --compile` за регуляркою `BUN_BUILD_COMPILE_RE` = `/\bbun\s+build\b[^\n]*\s--compile\b/iu` (нечутлива до регістру, юнікод-режим; шукає `bun build ... --compile` у межах одного рядка, бо `[^\n]*` забороняє перехід).
+
+Якщо тригер не спрацював — повертається `null`.
+
+Формування повідомлення (коли тригер спрацював):
+
+1. Створюється масив `problems` з одним обов'язковим повідомленням про антипатерн `bun build --compile` + нативний аддон. Список аддонів вставляється через `nativeAddons.join(', ')`. Повідомлення містить інструкцію канонічного фіксу: прибрати compile-крок, ship-нути `node_modules` і запускати через `bun <entry>` на базі `mirror.gcr.io/oven/bun:alpine` (з посиланням на `docker.mdc`). Entry-файл рекомендується брати з `--outfile`-таргета, `package.json#main` або `scripts.start`; якщо однозначно визначити неможливо — лишити TODO-маркер, **не вгадувати**.
+2. Якщо у `fileContent` додатково присутній патерн `apk add ... vips` (регулярка `APK_ADD_VIPS_RE` = `/\bapk\s+add\b[^\n]*\bvips\b/iu`) — додається друге повідомлення про те, що цей `apk add vips` зайвий: системний `libvips` не лікує брак `sharp.node`, його треба видалити разом із compile-кроком.
+3. Усі повідомлення з'єднуються через роздільник `'\n     - '` (новий рядок + 5 пробілів + `- `), щоб формат був придатний для рендеру в pretty-output лінтера як вкладений список.
+
+Side effects: відсутні. Чиста функція; жодних звернень до файлової системи, мережі чи глобального стану.
+
+## Залежності
+
+Зовнішні залежності модуля відсутні: ні npm-пакетів, ні Node-core модулів (`fs`/`path`/тощо) не імпортується. Файл — самодостатній.
+
+Внутрішні константи модуля (приватні, не експортуються):
+
+- `BUN_BUILD_COMPILE_RE` — `/\bbun\s+build\b[^\n]*\s--compile\b/iu`. Виявляє наявність флагу `--compile` біля `bun build` у межах одного рядка Dockerfile.
+- `APK_ADD_VIPS_RE` — `/\bapk\s+add\b[^\n]*\bvips\b/iu`. Виявляє пакет `vips` серед аргументів `apk add` у межах одного рядка.
+
+Зв'язки з іншими модулями репозиторію:
+
+- Логічно є частиною правила `docker` (`npm/rules/docker/...`). Викликається з check-обгортки правила, яка читає Dockerfile/`package.json` і запускає `getNativeAddonDeps` + `getNativeAddonNoCompileHint`.
+- Тематично пов'язаний із `../js/lint.mjs#getBunCompileHint` — там обробляється канон **без** нативних аддонів. Це окрема гілка з різним кінцевим артефактом (standalone-бінарник vs `bun <entry>`).
+- За структурою копіює `./docker-mirror.mjs` — той самий клас dep-специфічного чек-модуля.
+
+## Потік виконання / Використання
+
+Типовий сценарій інтеграції модуля у правило `docker`:
+
+1. Чекер правила читає `package.json` проєкту й бере поле `dependencies` (як `unknown`).
+2. Викликає `getNativeAddonDeps(dependencies)` — отримує відсортований список нативних аддонів (можливо порожній).
+3. Якщо список порожній — гілка перевірки завершується мовчки, нативно-аддонного антипатерну тут немає.
+4. Якщо список непорожній — чекер читає вміст Dockerfile/`Containerfile` як рядок і викликає `getNativeAddonNoCompileHint(fileContent, nativeAddons)`.
+5. Якщо результат — рядок, чекер додає його як помилку (зі схемою «hint») і пропонує канонічний фікс (відмова від `bun build --compile`; за наявності зайвого `apk add vips` — і його видалення).
+6. Якщо результат — `null`, чекер вважає Dockerfile сумісним з нативним аддоном.
+
+Приклад використання (псевдокод):
+
+```js
+import { getNativeAddonDeps, getNativeAddonNoCompileHint } from './docker-native-addon.mjs'
+
+const pkg = JSON.parse(await readFile('package.json', 'utf8'))
+const nativeAddons = getNativeAddonDeps(pkg.dependencies)
+if (nativeAddons.length > 0) {
+  const dockerfile = await readFile('Dockerfile', 'utf8')
+  const hint = getNativeAddonNoCompileHint(dockerfile, nativeAddons)
+  if (hint) reportError(hint)
+}
+```
+
+Властивості та інваріанти, на які покладаються виклики:
+
+- `getNativeAddonDeps` толерує будь-який вхід (`unknown`) і не кидає помилку.
+- `getNativeAddonNoCompileHint` толерує невалідний `nativeAddons` (через `Array.isArray`-перевірку) — повертає `null`, замість того щоб впасти.
+- Усі функції — чисті, без I/O, тож їх легко юніт-тестувати: достатньо передати рядкові константи й перевірити форму результату.
+- Регулярки навмисно прості (одна-рядкові, через `[^\n]*`), щоб уникати false-positive на багаторядкових heredoc/RUN-блоках; ціна — потрібно, щоб `bun build --compile` і `apk add vips` були записані в межах одного рядка (стандартна практика Dockerfile).
+
+Розширення модуля:
+
+- Додати новий точний пакет — внести його у `NATIVE_ADDON_PACKAGES`.
+- Додати новий scope, увесь вміст якого треба вважати нативним аддоном, — внести префікс у `NATIVE_ADDON_SCOPES` (з кінцевим `/`).
+- Додаткові підказки про супутні зайві системні залежності (за аналогією з `apk add vips`) додавайте через нові регулярки + умовний `problems.push(...)`.