@7n/rules 1.0.0

package/rules/doc-files/units-rs/main.mjs

@@ -0,0 +1,311 @@
+/** @see ./docs/units-rs.md */
+
+/**
+ * Пропускає рядковий літерал `"..."` (з escape-послідовностями).
+ * @param {string} src вміст файлу
+ * @param {number} i позиція відкриваючого `"`
+ * @returns {number} позиція ПІСЛЯ закриваючого `"`
+ */
+function skipString(src, i) {
+  i++ // відкриваючий "
+  while (i < src.length) {
+    if (src[i] === '\\') {
+      i += 2
+      continue
+    }
+    if (src[i] === '"') return i + 1
+    i++
+  }
+  return i
+}
+
+/**
+ * Пропускає рядковий (`//`) чи блочний коментар на позиції `i`.
+ * @param {string} src вміст файлу
+ * @param {number} i позиція `/` початку коментаря
+ * @returns {number} позиція ПІСЛЯ коментаря, або `-1` якщо на `i` не коментар
+ */
+function skipComment(src, i) {
+  if (src[i] !== '/') return -1
+  if (src[i + 1] === '/') {
+    const nl = src.indexOf('\n', i)
+    return nl === -1 ? src.length : nl + 1
+  }
+  if (src[i + 1] === '*') {
+    const end = src.indexOf('*/', i + 2)
+    return end === -1 ? src.length : end + 2
+  }
+  return -1
+}
+
+/**
+ * Знаходить індекс закриваючої `}` для відкриваючої `{` на позиції `start`.
+ * Правильно пропускає рядки/блочні коментарі та рядкові літерали.
+ * @param {string} src вміст файлу
+ * @param {number} start позиція відкриваючої `{`
+ * @returns {number} індекс `}` або -1, якщо не знайдено
+ */
+function findClosingBrace(src, start) {
+  let depth = 0
+  let i = start
+  while (i < src.length) {
+    const ch = src[i]
+    const afterComment = skipComment(src, i)
+    if (afterComment !== -1) {
+      i = afterComment
+      continue
+    }
+    if (ch === '"') {
+      i = skipString(src, i)
+      continue
+    }
+    if (ch === '{') {
+      depth++
+      i++
+      continue
+    }
+    if (ch === '}') {
+      depth--
+      if (depth === 0) return i
+      i++
+      continue
+    }
+    i++
+  }
+  return -1
+}
+
+/**
+ * Видобуває `///` doc-рядки безпосередньо перед рядком `lineIdx`.
+ * Сканує назад через `///`, `#[...]` та пусті рядки.
+ * @param {string[]} lines рядки файлу
+ * @param {number} lineIdx рядок декларації
+ * @returns {string} склеєний опис або ''
+ */
+function docBefore(lines, lineIdx) {
+  const doc = []
+  for (let i = lineIdx - 1; i >= 0; i--) {
+    const t = lines[i].trim()
+    if (t.startsWith('///')) {
+      doc.unshift(t.slice(3).trim())
+    } else if (t.startsWith('#[') || t.startsWith('#![') || t === '') {
+      // пропустити атрибути та пусті рядки
+    } else {
+      break
+    }
+  }
+  return doc.join(' ').trim()
+}
+
+// Pub-items матчаться у два кроки по trim-нутому рядку (прості регекспи без
+// бектрекінгу): спершу опційний pub(...)-префікс, потім сама декларація.
+// Також ловить fn без pub (для localSymbols і impl-методів)
+const PUB_PREFIX_RE = /^pub(?:\([^)]*\))?\s+/
+const ITEM_DECL_RE = /^(?:async\s+)?(?:unsafe\s+)?(fn|struct|enum|trait|type)\s+(\w+)/
+
+// impl Type { або impl<T> Trait for Type { — теж двокроково: голова `impl<...>`,
+// далі тип після `for` (trait-impl) або перше слово (inherent impl)
+const IMPL_HEAD_RE = /^impl(?:<[^>]*>)?\s+/
+const IMPL_FOR_TYPE_RE = /\bfor\s+(\w+)/
+const TYPE_NAME_RE = /^(\w+)/
+
+// Підозрілі exposure-атрибути, що роблять непуб-fn фактично публічними
+const EXPOSURE_ATTR_RE = /#\[(?:tauri::command|wasm_bindgen|uniffi::export|pyo3::pyfunction|napi)/
+
+// Базовий виклик fn-імені (для call-graph всередині юніта)
+const CALL_RE = /\b([a-z_]\w*)\s*\(/g
+
+/**
+ * Рахує дельту глибини `{}` в рядку, пропускаючи `//`-коментарі й рядкові літерали.
+ * @param {string} line рядок коду
+ * @returns {number} приріст глибини (додатний — відкрито більше, ніж закрито)
+ */
+function braceDeltaInLine(line) {
+  let delta = 0
+  let j = 0
+  while (j < line.length) {
+    const ch = line[j]
+    if (ch === '/' && line[j + 1] === '/') break
+    if (ch === '"') {
+      j++
+      while (j < line.length && line[j] !== '"') {
+        if (line[j] === '\\') j++
+        j++
+      }
+      j++
+      continue
+    }
+    if (ch === '{') delta++
+    else if (ch === '}') delta--
+    j++
+  }
+  return delta
+}
+
+/**
+ * Оновлює impl-стек за поточним рядком: прибирає закриті impl і, якщо рядок — impl-
+ * декларація на глибині ≤1, додає новий запис.
+ * @param {Array<{typeName:string, openDepth:number}>} implStack стек відкритих impl (мутується)
+ * @param {string} line сирий рядок
+ * @param {string} trimmed рядок без лідируючих пробілів
+ * @param {number} depth глибина ПІСЛЯ обробки рядка
+ * @param {number} depthAtStart глибина ДО обробки рядка
+ * @returns {void}
+ */
+function updateImplStack(implStack, line, trimmed, depth, depthAtStart) {
+  while (implStack.length > 0 && implStack.at(-1).openDepth > depth) {
+    implStack.pop()
+  }
+  if (depthAtStart <= 1) {
+    const headM = trimmed.match(IMPL_HEAD_RE)
+    if (headM && line.includes('{')) {
+      const rest = trimmed.slice(headM[0].length)
+      const typeM = rest.match(IMPL_FOR_TYPE_RE) ?? rest.match(TYPE_NAME_RE)
+      if (typeM) implStack.push({ typeName: typeM[1], openDepth: depth })
+    }
+  }
+}
+
+/**
+ * Витягує тіло item-а (fn/struct/enum/trait) через `findClosingBrace`.
+ * @param {string} src вміст файлу
+ * @param {string[]} lines рядки файлу
+ * @param {number} li індекс рядка декларації
+ * @param {number} lineOffset зсув початку рядка в `src`
+ * @param {string} kind вид item-а
+ * @returns {{body:string, itemEnd:number}} тіло та зсув кінця item-а
+ */
+function extractItemBody(src, lines, li, lineOffset, kind) {
+  let body = ''
+  let itemEnd = lineOffset + lines[li].length
+  if (kind !== 'type') {
+    const openBraceIdx = src.indexOf('{', lineOffset)
+    // Шукаємо `{` не далі ніж через 3 рядки від початку декларації
+    const threeLines = lines.slice(li, li + 3).join('\n').length
+    if (openBraceIdx !== -1 && openBraceIdx - lineOffset <= threeLines) {
+      const closeIdx = findClosingBrace(src, openBraceIdx)
+      if (closeIdx !== -1) {
+        itemEnd = closeIdx + 1
+        body = src.slice(lineOffset, itemEnd)
+      }
+    }
+  }
+  return { body, itemEnd }
+}
+
+/**
+ * Заповнює `calls` кожного юніта викликами інших юнітів цього ж файлу.
+ * @param {Array<{name:string, body:string, calls:string[]}>} units юніти файлу (мутуються)
+ * @returns {void}
+ */
+function fillCallGraph(units) {
+  const unitNames = new Set(units.map(u => u.name))
+  for (const u of units) {
+    if (!u.body) continue
+    const calls = new Set()
+    let cm
+    const re = new RegExp(CALL_RE.source, 'g')
+    while ((cm = re.exec(u.body)) !== null) {
+      if (unitNames.has(cm[1]) && cm[1] !== u.name) calls.add(cm[1])
+    }
+    u.calls = [...calls]
+  }
+}
+
+/**
+ * Обробляє рядок на глибині ≤1: якщо це декларація item-а — додає юніт у `units`;
+ * інакше скидає exposure-флаг на не-атрибутних рядках. Повертає новий стан флага.
+ * @param {object} p параметри
+ * @param {string} p.src вміст файлу
+ * @param {string[]} p.lines рядки файлу
+ * @param {number} p.li індекс рядка
+ * @param {number} p.lineOffset зсув початку рядка в `src`
+ * @param {number} p.depthAtStart глибина ДО обробки рядка
+ * @param {string|null} p.currentImpl тип поточного impl або `null`
+ * @param {boolean} p.nextFnExposed чи наступний fn exposure-exposed
+ * @param {Array<object>} p.units акумулятор юнітів (мутується)
+ * @returns {boolean} новий стан `nextFnExposed`
+ */
+function processItemLine({ src, lines, li, lineOffset, depthAtStart, currentImpl, nextFnExposed, units }) {
+  const line = lines[li]
+  const trimmed = line.trimStart()
+  const pubM = trimmed.match(PUB_PREFIX_RE)
+  const m = (pubM ? trimmed.slice(pubM[0].length) : trimmed).match(ITEM_DECL_RE)
+  if (!m) {
+    // Рядок не є item — скидаємо exposure-флаг якщо не атрибут
+    const t = line.trim()
+    if (!t.startsWith('#[') && !t.startsWith('#![') && !t.startsWith('///') && t !== '') return false
+    return nextFnExposed
+  }
+  const kind = m[1]
+  const isPub = Boolean(pubM) || (kind === 'fn' && nextFnExposed)
+  const doc = docBefore(lines, li)
+  // Витягуємо тіло через findClosingBrace для fn/struct/enum/trait
+  const { body, itemEnd } = extractItemBody(src, lines, li, lineOffset, kind)
+  units.push({
+    name: m[2],
+    kind,
+    exported: isPub,
+    implName: depthAtStart === 1 ? currentImpl : null,
+    span: { start: lineOffset, end: itemEnd },
+    body,
+    calls: [],
+    doc
+  })
+  return kind === 'fn' ? false : nextFnExposed
+}
+
+/**
+ * Юніт-екстрактор для `.rs` файлів.
+ * Визначає top-level і impl-методи через підрахунок дужок по рядках.
+ * Відомі обмеження: рядкові літерали з `{`/`}` всередині `{}` можуть дати
+ * хибну глибину (рідкісно в реальному Rust-коді з rustfmt).
+ * @param {string} src вміст файлу
+ * @param {string} [_relPath] резервний (не використовується)
+ * @returns {Array<{name:string, kind:string, exported:boolean, implName:string|null, span:{start:number,end:number}, body:string, calls:string[], doc:string}>|null} юніти файлу (fn та impl-методи) або `null`, якщо юнітів не знайдено
+ */
+export function extractUnitsRs(src, _relPath) {
+  const lines = src.split('\n')
+  const units = []
+  let depth = 0
+  let lineOffset = 0
+  // Стек відкритих impl: { typeName, openDepth }
+  const implStack = []
+  // Флаг: наступний fn отримує exposure (через #[tauri::command] тощо)
+  let nextFnExposed = false
+
+  for (let li = 0; li < lines.length; li++) {
+    const line = lines[li]
+    const depthAtStart = depth
+    depth += braceDeltaInLine(line)
+
+    updateImplStack(implStack, line, line.trimStart(), depth, depthAtStart)
+    const currentImpl = implStack.at(-1)?.typeName ?? null
+
+    // Перевіряємо exposure-атрибути
+    if (EXPOSURE_ATTR_RE.test(line)) {
+      nextFnExposed = true
+    }
+
+    // Елементи на глибині 0 (top-level) і 1 (всередині impl)
+    if (depthAtStart <= 1) {
+      nextFnExposed = processItemLine({
+        src,
+        lines,
+        li,
+        lineOffset,
+        depthAtStart,
+        currentImpl,
+        nextFnExposed,
+        units
+      })
+    }
+
+    lineOffset += line.length + 1 // +1 для '\n'
+  }
+
+  // Базовий call-graph: виклики інших юнітів цього файлу
+  fillCallGraph(units)
+
+  return units.length > 0 ? units : null
+}

package/rules/docker/docs/index.md

@@ -0,0 +1,11 @@
+---
+type: Directory Index
+title: npm/rules/docker
+resource: npm/rules/docker/
+---
+
+# npm/rules/docker
+
+| Файл                | Тип       |
+| ------------------- | --------- |
+| [main.mjs](main.md) | JS Module |

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

@@ -0,0 +1,60 @@
+/**
+ * Спільна логіка виклику hadolint для шляхів до Dockerfile (див. docker.mdc).
+ *
+ * Відносні шляхи з прямими слешами; hadolint резолвиться через `ensureTool`
+ * (PATH → кеш → авто-install brew/scoop/GitHub Release per-platform). Docker-fallback
+ * прибрано — hadolint ставиться як **нативний бінарник**, без `docker run`.
+ * Використовується `../js/lint.mjs` (правило `n-rules lint docker` / check-docker).
+ */
+import { spawnSync } from 'node:child_process'
+import { relative, sep } from 'node:path'
+
+import { ensureTool } from '../../../scripts/lib/ensure-tool.mjs'
+
+/**
+ * Відносний шлях від root з прямими слешами (стабільний вивід незалежно від OS).
+ * @param {string} root корінь
+ * @param {string} absPath абсолютний шлях
+ * @returns {string} відносний шлях з прямими слешами
+ */
+export function posixRel(root, absPath) {
+  return relative(root, absPath).split(sep).join('/')
+}
+
+/**
+ * Запуск hadolint як нативного бінарника. hadolint резолвиться через `ensureTool`
+ * (PATH → кеш → авто-install); якщо авто-install відключено (`N_CURSOR_NO_AUTO_INSTALL`)
+ * чи не вдався — повертаємо `ok: false` з підказкою (без `docker run`).
+ * @param {string} root корінь репозиторію
+ * @param {string} absPath абсолютний шлях до Dockerfile
+ * @returns {{ ok: boolean, stdout: string, stderr: string, via: string }} результат перевірки hadolint
+ */
+export function lintDockerfileWithHadolint(root, absPath) {
+  const rel = posixRel(root, absPath)
+  let hadolintPath
+  try {
+    hadolintPath = ensureTool('hadolint')
+  } catch (error) {
+    return {
+      ok: false,
+      stdout: '',
+      stderr:
+        `Не вдалося отримати hadolint (${error.message}). ` +
+        'Встанови: brew install hadolint (macOS) / scoop install hadolint (Windows) / ' +
+        'https://github.com/hadolint/hadolint/releases (Linux).',
+      via: 'hadolint'
+    }
+  }
+
+  const local = spawnSync(hadolintPath, [rel], {
+    cwd: root,
+    encoding: 'utf8',
+    maxBuffer: 10 * 1024 * 1024
+  })
+  return {
+    ok: local.status === 0,
+    stdout: local.stdout ?? '',
+    stderr: local.stderr ?? '',
+    via: 'hadolint'
+  }
+}

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

@@ -0,0 +1,148 @@
+/**
+ * Визначає, чи рядок `FROM` у Dockerfile використовує образи
+ * `oven/bun`, `alpine`, `nginx`, `node` з Docker Hub без дзеркала
+ * `mirror.gcr.io` (GCR mirror).
+ *
+ * Правило застосовується лише до тих самих звернень, що виглядають як
+ * pull з Docker Hub (короткі імена, `docker.io/…`); приватні реєстри
+ * (hostname у першому сегменті) не оцінюються.
+ *
+ * Канонічні заміни: `mirror.gcr.io/oven/bun` та
+ * `mirror.gcr.io/library/{alpine,nginx,node}`.
+ */
+
+const FROM_LINE_RE = /^\s*FROM\s+([^\n]+)/i
+const TOKEN_RE = /(?:[^\s"]+|"[^"]*")+/g
+const MIRROR_GCR_RE = /^mirror\.gcr\.io\//i
+const IP_LIKE_RE = /^\d+\.\d+/
+const HOST_PORT_RE = /^\S+:\d+$/
+const DOCKER_IO_PREFIX_RE = /^(docker\.io|index\.docker\.io)\//
+const NEWLINE_SPLIT_RE = /\r?\n/
+
+/**
+ * @param {string} t — токен образу в лапках або без
+ * @returns {string} токен без зовнішніх лапок
+ */
+function stripFromImageQuotes(t) {
+  if (t.length >= 2 && (t[0] === '"' || t[0] === "'")) {
+    return t.slice(1, -1)
+  }
+  return t
+}
+
+/**
+ * Виділяє токен образу з рядка `FROM` (після зняття inline-коментаря, без AS).
+ * Підтримує прапорець `--platform=…` і форму `--platform` + значення.
+ * @param {string} line — рядок Dockerfile
+ * @returns {string | null} токен образу або null, якщо рядок не `FROM`
+ */
+export function getFromImageToken(line) {
+  const withoutComment = line.split('#', 1)[0].trim()
+  if (!withoutComment) return null
+  const m = withoutComment.match(FROM_LINE_RE)
+  if (!m) return null
+  const raw = m[1].trim()
+  const tokens = raw.match(TOKEN_RE) || []
+  let i = 0
+  while (i < tokens.length) {
+    const t = tokens[i]
+    if (t === '--platform' || t.startsWith('--platform=')) {
+      if (t.startsWith('--platform=') || tokens[i + 1] === undefined) {
+        i += 1
+      } else {
+        i += 2
+      }
+    } else if (t === '--' || t.toUpperCase() === 'AS') {
+      break
+    } else if (t.startsWith('--')) {
+      i += 1
+    } else {
+      return stripFromImageQuotes(t)
+    }
+  }
+  return null
+}
+
+/**
+ * Схоже на звернення до Docker Hub (коротке ім’я, `docker.io/…`, не mirror.gcr.io).
+ * Не вважати Hub: явний чужий реєстр (`gcr.io/…`, `reg.example.com:5000/…`).
+ * @param {string} imageToken — ref образу (FROM)
+ * @returns {boolean} true, якщо схоже на pull з Docker Hub
+ */
+export function isDockerHubStyleImageRef(imageToken) {
+  if (!imageToken) return false
+  if (MIRROR_GCR_RE.test(imageToken)) return false
+  const noDigest = imageToken.split('@', 1)[0] || ''
+  if (!noDigest.includes('/')) {
+    return true
+  }
+  const first = noDigest.split('/', 1)[0] || ''
+  if (first === 'docker.io' || first === 'index.docker.io') return true
+  if (first.includes('.')) return false
+  if (first === 'localhost' || IP_LIKE_RE.test(first)) return false
+  return !(first.includes(':') && HOST_PORT_RE.test(first))
+}
+
+/**
+ * Нормалізує шлях репозиторію (без тега/digest) для порівняння: `library/node`, `oven/bun`, …
+ * @param {string} imageToken — ref образу
+ * @returns {string} нормалізований шлях репозиторію без тега
+ */
+export function normalizeHubRepoPath(imageToken) {
+  let s = (imageToken.split('@', 1)[0] || '').toLowerCase()
+  s = s.replace(DOCKER_IO_PREFIX_RE, '')
+  if (!s.includes('/')) {
+    return `library/${s.split(':', 1)[0]}`
+  }
+  const lastSl = s.lastIndexOf('/')
+  const lastCol = s.lastIndexOf(':')
+  if (lastCol > lastSl) {
+    s = s.slice(0, lastCol)
+  }
+  return s
+}
+
+const HUB_REPOS_REQUIRING_MIRROR = /** @type {const} */ (
+  new Set(['oven/bun', 'library/alpine', 'library/nginx', 'library/node', 'nginxinc/nginx-unprivileged'])
+)
+
+const EXPECTED_MIRROR = /** @type {const} */ ({
+  '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'
+})
+
+/**
+ * Якщо образ тягнеться з Hub і підлягає дзеркалу — повертає рекомендовану заміну, інакше `null`.
+ * @param {string} imageToken — ref після `FROM`
+ * @returns {string | null} рекомендований `mirror.gcr.io/...` (без тега) або null
+ */
+export function getRequiredMirrorGcrImage(imageToken) {
+  if (!imageToken) return null
+  if (MIRROR_GCR_RE.test(imageToken)) return null
+  if (!isDockerHubStyleImageRef(imageToken)) return null
+  const norm = normalizeHubRepoPath(imageToken)
+  if (!HUB_REPOS_REQUIRING_MIRROR.has(/** @type {keyof typeof EXPECTED_MIRROR} */ (norm))) {
+    return null
+  }
+  return EXPECTED_MIRROR[/** @type {keyof typeof EXPECTED_MIRROR} */ (norm)]
+}
+
+/**
+ * Сканує вміст Dockerfile / Containerfile — повертає рядок помилки або `null`.
+ * @param {string} fileContent — повний вміст Dockerfile
+ * @returns {string | null} повідомлення з номером рядка або null
+ */
+export function getMirrorGcrHint(fileContent) {
+  const lines = fileContent.split(NEWLINE_SPLIT_RE)
+  for (const [n, line] of lines.entries()) {
+    const image = getFromImageToken(line)
+    const expected = getRequiredMirrorGcrImage(image)
+    if (expected) {
+      return `рядок ${n + 1}: FROM має тягнути ${expected} (замість ${image})`
+    }
+  }
+  return null
+}

package/rules/docker/lib/docker-native-addon.mjs

@@ -0,0 +1,93 @@
+/**
+ * Перевірка для проєктів, що залежать від нативного `.node`-аддона, який вантажиться через
+ * **динамічний `require`** (передусім **sharp**; той самий клас — `@img/*`, `argon2`).
+ *
+ * Такі аддони **не можна** пакувати через `bun build --compile`: компілятор не трейсить
+ * динамічний `require(\`@img/sharp-${platform}/sharp.node\`)` і не вшиває нативний біндинг, тож
+ * компільований бінарник падає в рантаймі (`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`.
+ *
+ * Канон для таких проєктів — НЕ компілювати, а ship `node_modules` і запускати через
+ * `bun <entry>` на базі `mirror.gcr.io/oven/bun:alpine` (див. docker.mdc: компіляція). Це
+ * легітимний виняток до правила «лише alpine/scratch у фінальному stage» — тут потрібен
+ * саме bun-рантайм.
+ *
+ * Це окрема гілка від генеричного compile-правила (`getBunCompileHint` у `../js/lint.mjs`):
+ * для проєктів БЕЗ нативних аддонів standalone-бінарник на alpine лишається каноном.
+ *
+ * Взірець структури dep-специфічного чек-модуля — сусідній `./docker-mirror.mjs`.
+ */
+
+/**
+ * Розширюваний список нативних `.node`-аддонів із динамічним завантаженням біндингу.
+ * Точні імена пакетів.
+ */
+export const NATIVE_ADDON_PACKAGES = /** @type {const} */ (['sharp', 'argon2'])
+
+/**
+ * Scope-префікси нативних аддонів (будь-який пакет у scope трактуємо як нативний).
+ * `@img/*` — платформо-специфічні біндинги sharp (`@img/sharp-linuxmusl-arm64` тощо).
+ */
+export const NATIVE_ADDON_SCOPES = /** @type {const} */ (['@img/'])
+
+const BUN_BUILD_COMPILE_RE = /\bbun\s+build\b[^\n]*\s--compile\b/iu
+const APK_ADD_VIPS_RE = /\bapk\s+add\b[^\n]*\bvips\b/iu
+
+/**
+ * Чи ім'я пакета — нативний `.node`-аддон зі списку (точне ім'я або scope-префікс).
+ * @param {string} name — ім'я npm-пакета
+ * @returns {boolean} true, якщо це знаний нативний аддон
+ */
+export function isNativeAddonPackage(name) {
+  if (NATIVE_ADDON_PACKAGES.includes(/** @type {never} */ (name))) return true
+  return NATIVE_ADDON_SCOPES.some(scope => name.startsWith(scope))
+}
+
+/**
+ * Повертає імена нативних аддонів, наявних у `dependencies` пакета.
+ * @param {unknown} dependencies — об'єкт `package.json#dependencies`
+ * @returns {string[]} відсортовані імена знайдених нативних аддонів (порожній — якщо немає)
+ */
+export function getNativeAddonDeps(dependencies) {
+  if (!dependencies || typeof dependencies !== 'object' || Array.isArray(dependencies)) return []
+  return Object.keys(dependencies)
+    .filter(name => isNativeAddonPackage(name))
+    .toSorted((a, b) => a.localeCompare(b))
+}
+
+/**
+ * Перевіряє антипатерн «нативний аддон + `bun build --compile`».
+ *
+ * Тригер:
+ * - у `package.json#dependencies` є нативний аддон (`getNativeAddonDeps` непорожній);
+ * - **і** Dockerfile містить `bun build --compile`.
+ *
+ * Прапорцює compile-крок як помилку; додатково — зайвий `apk add ... vips`, доданий для
+ * компенсації (системний vips не рятує). Канон описано в docker.mdc.
+ * @param {string} fileContent — вміст Dockerfile/Containerfile
+ * @param {string[]} nativeAddons — знайдені нативні аддони (з `getNativeAddonDeps`)
+ * @returns {string | null} повідомлення помилки або null
+ */
+export function getNativeAddonNoCompileHint(fileContent, nativeAddons) {
+  if (!Array.isArray(nativeAddons) || nativeAddons.length === 0) return null
+  if (!BUN_BUILD_COMPILE_RE.test(fileContent)) return null
+
+  /** @type {string[]} */
+  const problems = [
+    `проєкт залежить від нативного .node-аддона (${nativeAddons.join(', ')}) з динамічним require — ` +
+      '`bun build --compile` не вшиває нативний біндинг, тож бінарник падає в рантаймі. ' +
+      'Прибери compile-крок: ship node_modules + `bun <entry>` на базі mirror.gcr.io/oven/bun:alpine ' +
+      '(docker.mdc: компіляція). Entry бери з наявного --outfile-таргета / package.json#main / ' +
+      'scripts.start; якщо не визначити — лиши TODO-маркер, не вгадуй'
+  ]
+
+  if (APK_ADD_VIPS_RE.test(fileContent)) {
+    problems.push(
+      'зайвий `apk add ... vips` — системний libvips не лікує брак `sharp.node`; прибери разом із compile-кроком'
+    )
+  }
+
+  return problems.join('\n     - ')
+}