@7n/rules 1.41.0 → 1.43.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## [1.43.0] - 2026-07-22
+
+### Added
+
+- docker: n-rules:bun-no-compile-маркер (# n-rules:bun-no-compile: <причина>) — генералізує native-addon-виняток на будь-яку недосяжну для checker-а причину неможливості bun build --compile (напр. динамічний import() рантайм-конфігу); вимикає вимогу компіляції й дозволяє mirror.gcr.io/oven/bun:* як фінальний stage
+
+## [1.42.0] - 2026-07-22
+
+### Added
+
+- warnAboutRulesWithoutConcerns: попередження, якщо rule-id з .n-rules.json#rules не знайдено в жодному rulesDir (ядро+плагіни) — ловить дрейф конфігу після переїзду concern-ів у плагін
+
 ## [1.41.0] - 2026-07-22
 
 ### Fixed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@7n/rules",
-  "version": "1.41.0",
+  "version": "1.43.0",
   "description": "CLI еталонних правил і skills (префікс n-): синк у репозиторій, дельта-lint, конформність",
   "keywords": [
     "cli",

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

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

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

@@ -3,45 +3,49 @@ type: JS Module
 title: main.mjs
 resource: npm/rules/docker/lint/main.mjs
 docgen:
-  crc: 26fdea23
-  model: omlx/gemma-4-e4b-it-OptiQ-4bit
-  score: 100
-  issues: judge:inaccurate:0.99
+  crc: 7cc8c2c7
+  model: openai-codex/gpt-5.4-mini
+  tier: cloud-min
+  score: 90
+  issues: internal-name:checkDockerfile,judge-refine:kept-original,judge:inaccurate:0.99
   judgeModel: openai-codex/gpt-5.4-mini
 ---
 
 ## Огляд
 
-Please provide the content of the file you want me to document. I need the code or at least the context file to proceed with generating the "Огляд" section based on the provided "Поведінка".
+Файл знаходить Dockerfile і Containerfile в межах репозиторію через `findDockerfilePaths`, визначає stage-структуру через `splitDockerfileStages` і `parseFromStages`, а потім запускає `lint` як fail-safe перевірку без винесення винятків назовні.  
+Перевірки спираються на правила з `docker.mdc` і окремо покривають multistage/runtime-узгодженість через `getMultistageAndRuntimeHint`, `getBunCompileHint`, `getNginxAlpineSlimTagHint` і `getNonRootRuntimeHint`, щоб Docker-образи відповідали очікуваній схемі збірки та запуску.
 
 ## Поведінка
 
-Поведінка:
-isDockerfileName визначає, чи є вказане ім'я файлу Dockerfile або Containerfile.
-findDockerfilePaths збирає абсолютні шляхи до всіх Dockerfile / Containerfile, ігноруючи задані шляхи.
-parseFromStages витягує всі інструкції `FROM <image>` з вмісту Dockerfile/Containerfile.
-splitDockerfileStages розбиває вміст Dockerfile на логічні етапи на основі інструкцій `FROM`.
-getMultistageAndRuntimeHint перевіряє, чи відповідає структура Dockerfile вимогам багатоетапної збірки та дозволених runtime-образів (docker.mdc).
-getBunCompileHint перевіряє, чи для bun-проєктів на backend runtime виконується необхідна компіляція бінарника та не міститься залишків build tooling.
-getNginxAlpineSlimTagHint перевіряє, що для nginx-образів у `FROM` вказано тег `alpine-slim` (docker.mdc).
-getNonRootRuntimeHint перевіряє наявність інструкції `USER <non-root>` у фінальному stage (docker.mdc).
-main виконує повний перегляд знайдених Dockerfile / Containerfile, застосовуючи перевірки, що спираються на конфіги, зокрема `package.json`, та запускаючи hadolint.
-lint є оркестратором, який запускає `main` для перевірки усього репозиторію.
+Detector спочатку знаходить лише Dockerfile і Containerfile у межах репозиторію, відфільтровуючи імена через `isDockerfileName` та враховуючи ignore-маршрути, а далі для кожного файлу запускає послідовну перевірку в межах `lint`.
+
+`parseFromStages` і `splitDockerfileStages` дають спільну картину структури файла: перший витягує всі базові образи, другий ділить вміст на stages, щоб наступні перевірки могли оцінювати саме фінальний runtime і build-stage окремо.
+
+`getMultistageAndRuntimeHint` використовує ці дані, щоб вимагати multistage і дозволений фінальний runtime відповідно до `docker.mdc`; для bun-runtime робить виняток лише коли є нативний `.node`-аддон або явний `# n-rules:bun-no-compile` маркер. Такий маркер читає `hasBunNoCompileMarker`, і він служить opt-in для випадків, які не можна вивести механічно.
+
+`getBunCompileHint` працює лише для bun-проєктів із backend runtime: якщо в образі є `bun install` або `bun i`, але немає compile-кроку в build-stage, або в фінальному stage лишився bun tooling, це вважається порушенням. Вимога спирається на `package.json`, щоб зрозуміти, чи проект справді bun-орієнтований.
+
+`getNonRootRuntimeHint` перевіряє, що фінальний runtime не працює як root, а `getNginxAlpineSlimTagHint` звужує окреме правило для nginx-образів до потрібного тегу з `docker.mdc`.
+
+Усі ці перевірки збираються в `checkDockerfile`, який для кожного знайденого файла формує violations і додає їх до результату через fail-safe підхід: помилки не виходять назовні, а перетворюються на контрольований lint-результат.
+
+`lint` є єдиною точкою запуску для цього detector: вона знаходить файли, проганяє їх через `checkDockerfile` і повертає підсумок для всього репозиторію без запису стану.
 
 ## Публічний API
 
-isDockerfileName — визначає, чи є ім'я файлу Dockerfile або Containerfile (включаючи варіації типу `Dockerfile.prod`).
-findDockerfilePaths — збирає повні шляхи до файлів Dockerfile або Containerfile, починаючи з поточного каталогу.
-parseFromStages — витягує список усіх образів, вказаних у директивах `FROM` у файлі Dockerfile/Containerfile.
-splitDockerfileStages — розділяє Dockerfile на логічні етапи (stages) на основі інструкцій `FROM`.
-getMultistageAndRuntimeHint — аналізує вимоги до структури багатоетапного збігу: перевіряє, чи є мінімум два етапи з `FROM`, а також чи відповідають образи фінального етапу дозволеним типам (з урахуванням винятків для проєктів з нативними `.node-аддонами`).
-getBunCompileHint — перевіряє, чи вимагає проєкт на backend runtime, що збірка збігається у бінарний файл.
-getNginxAlpineSlimTagHint — для Nginx-образів перевіряє, чи вказано тег `alpine-slim` у відповідному `FROM`, згідно з `docker.mdc`.
-getNonRootRuntimeHint — перевіряє, чи фінальний етап виконання використовує інструкцію `USER` для роботи від імені не-root користувача, згідно з `docker.mdc`.
-main — проводить лінт-перевірку Dockerfile/Containerfile із використанням hadolint відповідно до `docker.mdc`.
-lint — є адаптером, що викликає стандартний лінтер `n-rules lint docker` для обгортання основної логіки.
+- isDockerfileName — Чи є basename Dockerfile / Containerfile (у т.ч. Dockerfile.prod).
+- findDockerfilePaths — Збирає абсолютні шляхи до Dockerfile / Containerfile від кореня cwd.
+- parseFromStages — Витягує всі `FROM <image>` зі вмісту Dockerfile/Containerfile.
+- hasBunNoCompileMarker — Явний opt-in консюмера: коментар-рядок `# n-rules:bun-no-compile: <причина>` будь-де у файлі позначає, що `bun build --compile` неможливий з причини поза виявними класами (на відміну від нативних `.node`-аддонів, які виявляються з `package.json#dependencies`).
+- splitDockerfileStages — Розбиває Dockerfile на stages за `FROM` (порожній масив, якщо FROM немає).
+- getMultistageAndRuntimeHint — Перевіряє multistage (мінімум 2 FROM) і дозволений фінальний runtime-образ (docker.mdc); для нативного `.node`-аддона або `n-rules:bun-no-compile`-маркера додатково дозволяє `mirror.gcr.io/oven/bun:*`.
+- getBunCompileHint — Для backend bun-проєкту (є `bun install`, фінальний FROM — alpine, не frontend, немає `n-rules:bun-no-compile`-маркера) вимагає `bun build --compile` у build stage і відсутність `bun` у фінальному stage.
+- getNginxAlpineSlimTagHint — Перевіряє, що для nginx-образів (`mirror.gcr.io/nginxinc/nginx-unprivileged`) у `FROM` вказано тег `alpine-slim` (docker.mdc).
+- getNonRootRuntimeHint — Перевіряє, що у фінальному stage є `USER <name|uid>` і це не `root`/`0` (docker.mdc).
+- lint — Detector docker/lint: Dockerfile/Containerfile — mirror/multistage/runtime/non-root + hadolint.
 
 ## Гарантії поведінки
 
-- Read-only: не виконує операцій запису (ФС/БД).
+- Власних операцій запису (ФС/БД) у файлі немає; виклики імпортованих модулів можуть писати.
 - Перехоплює помилки і не пропускає винятків назовні (fail-safe).

package/rules/docker/lint/main.mjs

@@ -15,6 +15,7 @@ const BUN_INSTALL_RE = /\bbun\s+(?:install|i)\b/iu
 const BUN_BUILD_COMPILE_RE = /\bbun\s+build\b[^\n]*\s--compile\b/iu
 const BUN_WORD_RE = /\bbun\b/iu
 const USER_LINE_RE = /^\s*USER\s+([^\s#]+)/iu
+const BUN_NO_COMPILE_MARKER_RE = /^#\s*n-rules:bun-no-compile:(.*)$/iu
 
 const NGINX_UNPRIVILEGED_MIRROR_PREFIX = 'mirror.gcr.io/nginxinc/nginx-unprivileged'
 
@@ -81,22 +82,39 @@ const RUNTIME_IMAGES = /** @type {const} */ ([
 /** @type {RegExp} */
 const DEBIAN_VIA_MIRROR_RE = /^mirror\.gcr\.io\/library\/debian:(.+)$/i
 
-/** Bun-рантайм як фінальний stage — легітимний лише за наявності нативного .node-аддона (див. docker.mdc). */
+/** Bun-рантайм як фінальний stage — легітимний лише за наявності нативного .node-аддона або `n-rules:bun-no-compile`-маркера (див. docker.mdc). */
 const BUN_RUNTIME_IMAGE = 'mirror.gcr.io/oven/bun'
 
+/**
+ * Явний opt-in консюмера: сервіс не можна пакувати через `bun build --compile` з причини, яку
+ * checker не може вивести механічно (динамічний `import()` рантайм-конфігу тощо — на відміну
+ * від нативних `.node`-аддонів, які виявляються з `package.json#dependencies`). Маркер —
+ * коментар-рядок `# n-rules:bun-no-compile: <причина>` будь-де у файлі; той самий канон, що й для
+ * native-addon: ship `node_modules` + `bun <entry>` на `mirror.gcr.io/oven/bun:*`.
+ * @param {string} fileContent вміст Dockerfile/Containerfile
+ * @returns {boolean} true, якщо маркер присутній із непорожньою причиною
+ */
+export function hasBunNoCompileMarker(fileContent) {
+  return fileContent.split(NEWLINE_RE).some(line => {
+    const m = line.trim().match(BUN_NO_COMPILE_MARKER_RE)
+    return Boolean(m && m[1].trim().length > 0)
+  })
+}
+
 /**
  * Чи ref фінального `FROM` відповідає дозволеним у docker.mdc (multistage / runtime).
  * @param {string} lastLower ref без digest, lower case
- * @param {boolean} [hasNativeAddon] чи проєкт залежить від нативного .node-аддона (sharp/@img/argon2)
+ * @param {boolean} [allowBunRuntime] чи легітимний bun-рантайм як фінальний stage (нативний аддон або `n-rules:bun-no-compile`-маркер)
  * @returns {boolean} true, якщо образ дозволений як фінальний runtime
  */
-function isAllowedFinalRuntimeImage(lastLower, hasNativeAddon = false) {
+function isAllowedFinalRuntimeImage(lastLower, allowBunRuntime = false) {
   if (lastLower === 'scratch' || lastLower.startsWith('scratch:')) {
     return true
   }
-  // Для нативних аддонів канон — ship node_modules + `bun <entry>`, тож фінальний stage на
-  // mirror.gcr.io/oven/bun:* легітимний (compile неможливий, див. docker-native-addon.mjs).
-  if (hasNativeAddon && (lastLower === BUN_RUNTIME_IMAGE || lastLower.startsWith(`${BUN_RUNTIME_IMAGE}:`))) {
+  // Канон — ship node_modules + `bun <entry>`, тож фінальний stage на mirror.gcr.io/oven/bun:*
+  // легітимний, коли compile неможливий (native-addon: docker-native-addon.mjs, або явний
+  // n-rules:bun-no-compile-маркер: hasBunNoCompileMarker).
+  if (allowBunRuntime && (lastLower === BUN_RUNTIME_IMAGE || lastLower.startsWith(`${BUN_RUNTIME_IMAGE}:`))) {
     return true
   }
   const deb = lastLower.match(DEBIAN_VIA_MIRROR_RE)
@@ -132,7 +150,8 @@ export function splitDockerfileStages(fileContent) {
  * Перевіряє базові вимоги до структури Dockerfile:
  * - multistage: мінімум 2 FROM
  * - фінальний FROM: дозволені образи в docker.mdc (alpine, scratch, debian slim, php, python, nginx, openresty, …);
- *   для проєктів із нативним .node-аддоном додатково дозволено mirror.gcr.io/oven/bun:* (bun-рантайм)
+ *   для проєктів із нативним .node-аддоном або `n-rules:bun-no-compile`-маркером додатково дозволено
+ *   mirror.gcr.io/oven/bun:* (bun-рантайм)
  * @param {string} fileContent вміст Dockerfile/Containerfile
  * @param {{ hasNativeAddon?: boolean }} [opts] опції: hasNativeAddon — є нативний .node-аддон (sharp/@img/argon2)
  * @returns {string | null} повідомлення помилки або null
@@ -148,8 +167,9 @@ export function getMultistageAndRuntimeHint(fileContent, { hasNativeAddon = fals
   const last = stages.at(-1)
   const lastImage = (last?.image || '').split('@', 1)[0] || ''
   const lastLower = lastImage.toLowerCase()
+  const allowBunRuntime = hasNativeAddon || hasBunNoCompileMarker(fileContent)
 
-  if (!isAllowedFinalRuntimeImage(lastLower, hasNativeAddon)) {
+  if (!isAllowedFinalRuntimeImage(lastLower, allowBunRuntime)) {
     return `фінальний FROM має бути дозволеним runtime-образом (див. docker.mdc: multistage), зараз: ${last?.image} (рядок ${last?.line})`
   }
 
@@ -161,7 +181,9 @@ export function getMultistageAndRuntimeHint(fileContent, { hasNativeAddon = fals
  *
  * Тригер:
  * - у Dockerfile є крок `bun install` (або `bun i`);
- * - фінальний FROM — `mirror.gcr.io/library/alpine:*` (тобто не nginx/openresty frontend).
+ * - фінальний FROM — `mirror.gcr.io/library/alpine:*` (тобто не nginx/openresty frontend);
+ * - немає `n-rules:bun-no-compile`-маркера (явний opt-in консюмера — compile неможливий з причини поза
+ *   виявними класами на кшталт нативних аддонів, напр. динамічний `import()` рантайм-конфігу).
  *
  * Очікування:
  * - у build stage є `bun build --compile`;
@@ -170,6 +192,8 @@ export function getMultistageAndRuntimeHint(fileContent, { hasNativeAddon = fals
  * @returns {string | null} повідомлення помилки або null
  */
 export function getBunCompileHint(fileContent) {
+  if (hasBunNoCompileMarker(fileContent)) return null
+
   const stages = splitDockerfileStages(fileContent)
   if (stages.length === 0) return null
 

package/rules/docker/main.mdc

@@ -132,6 +132,30 @@ CMD ["bun", "src/index.js"]
 
 Для проєктів **без** нативних аддонів standalone-бінарник на alpine лишається каноном (див. розділ вище про компіляцію).
 
+## Виняток: явний `n-rules:bun-no-compile`-маркер (причина поза виявними класами)
+
+Нативний `.node`-аддон — механічно виявна причина (є в `package.json#dependencies`). Але бувають причини, які checker вивести не може: наприклад, сервіс завантажує конфіг через динамічний `import()` шляху, невідомого на момент компіляції, — `bun build --compile` такий шлях не трейсить, тож бінарник падає в рантаймі так само, як із нативним аддоном.
+
+Для цих випадків — явний opt-in консюмера: коментар-рядок `# n-rules:bun-no-compile: <причина>` будь-де у Dockerfile/Containerfile (причина обов'язкова, непорожня). Маркер вимикає і вимогу `bun build --compile` (розділ «Компіляція bun-проєкту в бінарник»), і заборону `mirror.gcr.io/oven/bun:*` як фінального stage (розділ «Multistage build») — той самий канон, що й для нативних аддонів: ship `node_modules` + `bun <entry>` на `mirror.gcr.io/oven/bun:alpine`.
+
+```dockerfile
+# n-rules:bun-no-compile: gateway.config.js вантажиться через динамічний import(), compile не трейсить його
+FROM mirror.gcr.io/oven/bun:alpine AS build-env
+WORKDIR /app
+COPY package.json .
+RUN bun install --production
+COPY ./src ./src
+
+FROM mirror.gcr.io/oven/bun:alpine
+WORKDIR /app
+COPY --from=build-env --chown=bun:bun /app/node_modules ./node_modules
+COPY --from=build-env --chown=bun:bun /app/src ./src
+USER bun
+CMD ["bun", "src/index.js"]
+```
+
+Маркер — **не** заміна нативно-аддонного винятку (той визначається автоматично з `package.json`) і **не** привід уникати компіляції там, де вона можлива — це escape hatch для нового, не закодованого в checker класу причин; використовуй лише коли `bun build --compile` доведено не працює. Перевіряють `hasBunNoCompileMarker` / `getBunCompileHint` / `getMultistageAndRuntimeHint` у **`npm/rules/docker/lint/main.mjs`**.
+
 ## Non-root принцип у фінальному stage
 
 Для всіх образів потрібно щоб використовувся non-root принцип. **Спосіб** досягнення non-root залежить від **бази**, а не від зміни ОС — змінювати дистрибутив (Alpine→Debian) заради лише non-root **не треба**. Два шляхи:

package/scripts/lib/lint-surface/docs/run-detectors.md

@@ -3,7 +3,7 @@ type: JS Module
 title: run-detectors.mjs
 resource: npm/scripts/lib/lint-surface/run-detectors.mjs
 docgen:
-  crc: 128fe3b7
+  crc: a0f45fc3
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 100
   issues: judge:inaccurate:0.98
@@ -40,3 +40,5 @@ detectAll виконує прохід лінтера у режим детекц
 **Multi-dir (плагіни):** `effectiveRulesDirs` додає rules-каталоги плагінів з `.n-rules.json` (hot-path: без install, quiet); `readLintConcernsByRuleMulti` зливає концерни за іменем (перший власник виграє) — плагін може додавати концерни до правила ядра (mixin).
 
 **Capability-гейт:** `filterByCapabilities` відкидає концерни з незадоволеним `requires.capability` (capabilities надають встановлені плагіни через маніфест `n-rules.capabilities`; явний `opts.capabilities` у тестах перекриває резолв).
+
+**Warning про rule-id без concern-ів:** якщо rule-id з `.n-rules.json#rules` не має жодного concern-а серед усіх `rulesDirs` (ядро + плагіни) — `console.error` попереджає про можливий дрейф конфігу (типово: правило переїхало в плагін, якого консюмер не підключив у `plugins[]`). Rule-id з існуючим каталогом, але без `concern.json` (документаційні правила на кшталт `feedback`), warning не тригерить.

package/scripts/lib/lint-surface/run-detectors.mjs

@@ -152,15 +152,70 @@ async function readLintConcernsByRuleMulti(rulesDirs) {
   return merged
 }
 
+/**
+ * Імена ВСІХ каталогів верхнього рівня під `rulesDirs` — незалежно від того, чи знайшлись
+ * у них concern-и. Потрібно, щоб відрізнити «каталог є, просто без lint-поверхні» (легітимно
+ * для суто-документаційних правил на кшталт `feedback`/`local-ai`) від «каталогу немає
+ * взагалі ні в ядрі, ні в жодному підключеному плагіні» (ознака дрейфу конфігу — типово
+ * правило переїхало в плагін, якого консюмер не підключив).
+ * @param {string[]} rulesDirs rules-каталоги (ядро + плагіни).
+ * @returns {Promise<Set<string>>} унікальні імена каталогів-правил.
+ */
+async function discoverAllRuleDirNames(rulesDirs) {
+  const { readdir } = await import('node:fs/promises')
+  /** @type {Set<string>} */
+  const names = new Set()
+  for (const dir of rulesDirs) {
+    let entries
+    try {
+      entries = await readdir(dir, { withFileTypes: true })
+    } catch {
+      continue
+    }
+    for (const e of entries) {
+      if (e.isDirectory() && !e.name.startsWith('.')) names.add(e.name)
+    }
+  }
+  return names
+}
+
+/**
+ * Попереджає про rule-id з `.n-rules.json#rules`, яких немає ЖОДНИМ каталогом ні в ядрі, ні
+ * в підключених плагінах (не плутати з «каталог є, але без concern-ів» — легітимний випадок
+ * для суто-документаційних правил). Типова причина: правило переїхало в окремий плагін
+ * (напр. `js` → `@7n/rules-lang-js` з фази 5c), а `plugins[]` консюмера про це не знає —
+ * тоді перевірки для цього правила мовчки НЕ виконуються (0 знайдених concern-ів виглядає
+ * як «усе чисто», хоча насправді нічого не перевірялось).
+ * @param {Record<string, ConcernMeta[]>} byRule concerns згруповані за rule-id (з усіх rulesDirs).
+ * @param {import('../read-n-rules-config-lite.mjs').LiteConfig} config розпарсений .n-rules.json.
+ * @param {string[]} rulesDirs rules-каталоги (ядро + плагіни), для перевірки «каталог є, але порожній».
+ * @returns {Promise<void>}
+ */
+async function warnAboutRulesWithoutConcerns(byRule, config, rulesDirs) {
+  const missing = config.rules.filter(id => !(id in byRule))
+  if (missing.length === 0) return
+  const allDirNames = await discoverAllRuleDirNames(rulesDirs)
+  for (const ruleId of missing) {
+    if (allDirNames.has(ruleId)) continue // каталог є, просто без lint-поверхні — легітимно
+    console.error(
+      `⚠️  .n-rules.json: правило "${ruleId}" не знайдено НІ В ОДНОМУ з rulesDirs (ні в ядрі, ні в ` +
+        `підключених плагінах "plugins") — перевірки для нього НЕ виконуються. Якщо правило нещодавно ` +
+        `переїхало в окремий плагін, додай відповідний пакет у "plugins" (і в devDependencies).`
+    )
+  }
+}
+
 /**
  * Активні rule-id з `.n-rules.json` (для delta/full режимів).
  * @param {Record<string, ConcernMeta[]>} byRule concerns згруповані за rule-id.
  * @param {string} cwd робоча директорія прогону.
+ * @param {string[]} rulesDirs rules-каталоги (ядро + плагіни) — для warning про відсутні правила.
  * @returns {Promise<string[]>} перелік активних rule-id.
  */
-async function enabledRuleIds(byRule, cwd) {
+async function enabledRuleIds(byRule, cwd, rulesDirs) {
   const config = await readNRulesConfigLite(cwd)
   if (!config.exists) return []
+  await warnAboutRulesWithoutConcerns(byRule, config, rulesDirs)
   return Object.keys(byRule).filter(id => isRuleEnabled(config, id))
 }
 
@@ -189,7 +244,8 @@ function sortEntries(entries) {
  * @returns {Promise<PlanItem[]>} впорядкований план прогону.
  */
 export async function buildDetectPlan(opts) {
-  const byRule = await filterByCapabilities(await readLintConcernsByRuleMulti(await effectiveRulesDirs(opts)), opts)
+  const rulesDirs = await effectiveRulesDirs(opts)
+  const byRule = await filterByCapabilities(await readLintConcernsByRuleMulti(rulesDirs), opts)
   return buildPlan({
     byRule,
     full: opts.full === true,
@@ -198,7 +254,8 @@ export async function buildDetectPlan(opts) {
     pathMode: opts.pathMode === true,
     repoWide: opts.repoWide === true,
     baseRef: typeof opts.baseRef === 'string' ? opts.baseRef : null,
-    cwd: opts.cwd
+    cwd: opts.cwd,
+    rulesDirs
   })
 }
 
@@ -209,8 +266,9 @@ export async function buildDetectPlan(opts) {
  * @returns {Promise<{ byRule: Record<string, ConcernMeta[]>, enabledSet: Set<string> }>} concerns і активні правила.
  */
 export async function loadEnabledLintRules(opts) {
-  const byRule = await filterByCapabilities(await readLintConcernsByRuleMulti(await effectiveRulesDirs(opts)), opts)
-  const enabledSet = new Set(await enabledRuleIds(byRule, opts.cwd))
+  const rulesDirs = await effectiveRulesDirs(opts)
+  const byRule = await filterByCapabilities(await readLintConcernsByRuleMulti(rulesDirs), opts)
+  const enabledSet = new Set(await enabledRuleIds(byRule, opts.cwd, rulesDirs))
   return { byRule, enabledSet }
 }
 
@@ -378,6 +436,7 @@ export function computeActiveDomains(byRule, enabledSet, changed) {
  * @param {boolean} [args.repoWide] `--repo-wide`: лише full-scope concerns, whole-repo.
  * @param {string|null} [args.baseRef] явна база дельти (`--base <ref>`) замість каскаду main→origin/main.
  * @param {string} args.cwd робоча директорія прогону.
+ * @param {string[]} [args.rulesDirs] rules-каталоги (ядро + плагіни) — для warning про відсутні правила.
  * @returns {Promise<PlanItem[]>} впорядкований план прогону.
  */
 async function buildPlan({
@@ -388,14 +447,15 @@ async function buildPlan({
   pathMode = false,
   repoWide = false,
   baseRef = null,
-  cwd
+  cwd,
+  rulesDirs = []
 }) {
   // scoped + --path: per-file concerns названих правил × перетин path ∩ дельта
   if (rules.length > 0 && explicitFiles !== null) return buildScopedDeltaPlan(byRule, rules, explicitFiles)
   // scoped: усі lint-concerns названих правил, whole-repo
   if (rules.length > 0) return buildScopedPlan(byRule, rules)
 
-  const enabled = await enabledRuleIds(byRule, cwd)
+  const enabled = await enabledRuleIds(byRule, cwd, rulesDirs)
   const enabledSet = new Set(enabled)
 
   // repo-wide: лише full-scope concerns (окремий CI-workflow, не гейтить деплой)
@@ -557,7 +617,8 @@ export async function detectAll(opts) {
   const verbose = opts.verbose === true
   const baseLog = opts.log ?? (s => process.stdout.write(s))
 
-  const byRule = await filterByCapabilities(await readLintConcernsByRuleMulti(await effectiveRulesDirs(opts)), opts)
+  const rulesDirs = await effectiveRulesDirs(opts)
+  const byRule = await filterByCapabilities(await readLintConcernsByRuleMulti(rulesDirs), opts)
   const plan = await buildPlan({
     byRule,
     full,
@@ -566,7 +627,8 @@ export async function detectAll(opts) {
     pathMode: opts.pathMode === true,
     repoWide: opts.repoWide === true,
     baseRef: typeof opts.baseRef === 'string' ? opts.baseRef : null,
-    cwd
+    cwd,
+    rulesDirs
   })
 
   // Detect-only бар — ЛИШЕ в TTY (без тикера «виправлено»). У не-TTY (hooks, CI-gate,

package/scripts/utils/ast-scan-utils.mjs

@@ -115,7 +115,7 @@ export function parseProgramOrNull(content, virtualPath) {
 
 /**
  * Парсить файл і повертає `{ program, comments }` або null. Окремий вхід для перевірок,
- * яким потрібні коментарі (наприклад, маркер `// allow-unsafe: ...` біля виклику) —
+ * яким потрібні коментарі (наприклад, маркер `// n-rules:allow-unsafe: ...` біля виклику) —
  * базовий `parseProgramOrNull` свідомо лишається без коментарів, щоб не змінювати API.
  * @param {string} content вихідний код
  * @param {string} virtualPath шлях для вибору `lang` (також для діагностики)

package/scripts/utils/docs/ast-scan-utils.md

@@ -3,52 +3,53 @@ type: JS Module
 title: ast-scan-utils.mjs
 resource: npm/scripts/utils/ast-scan-utils.mjs
 docgen:
-  crc: ed9f189b
+  crc: 0a015cfc
+  model: openai-codex/gpt-5.4-mini
+  tier: cloud-min
+  score: 100
+  issues: judge:error
+  judgeModel: openai-codex/gpt-5.4-mini
 ---
 
-Цей файл містить утиліти для AST-сканерів JavaScript та TypeScript, що використовуються для аналізу коду та виявлення потенційних проблем. Він надає інструменти для обробки AST, перетворення даних та взаємодії з різними типами вузлів, забезпечуючи основу для створення правил безпеки та аналізу коду. Ці утиліти спрощують розробку сканерів, усуваючи необхідність повторного написання boilerplate-коду.
+## Огляд
+
+Утиліти для AST-сканерів JS/TS на `oxc-parser`: `langFromPath` вибирає мову за шляхом файлу, `offsetToLine` переводить зміщення в номер рядка, `normalizeSnippet` стискає фрагмент коду, а `parseProgramOrNull` і `parseProgramAndCommentsOrNull` безпечно повертають `null` замість винятку, коли розбір не вдався.
+
+Файл також надає спільні засоби для аналізу дерева й контексту: `walkAstWithAncestors` обходить AST разом із предками, `isFunctionNode` і `isJoinCall` розпізнають типові вузли, `templateQuasisText` та `isSqlListContextTemplate` допомагають працювати з `TemplateLiteral`, а `requireCallModule` і `dynamicImportModule` виділяють модуль із викликів імпорту.
 
 ## Поведінка
 
-langFromPath: Визначає мову (js, jsx, ts, tsx) на основі розширення файлу.
-offsetToLine: Перетворює байтове зміщення в номер рядка для текстового файлу.
-normalizeSnippet: Стискає текстовий фрагмент до 180 символів, видаляючи пробіли.
-isFunctionNode: Визначає, чи є вузол AST функцією (FunctionDeclaration, FunctionExpression, ArrowFunctionExpression).
-walkAstWithAncestors: Рекурсивно обходить AST, збираючи предки вузла.
-parseProgramOrNull: Парсує файл JS/TS та повертає програму або null, якщо є помилки.
-parseProgramAndCommentsOrNull: Парсує файл JS/TS та повертає програму та список коментарів, або null, якщо є помилки.
-isJoinCall: Визначає, чи є виклик `join` у TemplateLiteral.
-templateQuasisText: Збирає текст quasis з TemplateLiteral.
-isSqlListContextTemplate: Визначає, чи є TemplateLiteral контекстом SQL-списку (IN/VALUES).
-requireCallModule: Витягує ім'я модуля з аргументу виклику `require`.
-dynamicImportModule: Витягує ім'я модуля з аргументу виклику `import`.
+Утиліти працюють як спільний шар для AST-сканерів: спочатку за шляхом файлу визначається мова парсингу, далі текст розбирається в `program`, а для перевірок, яким потрібні коментарі поруч із кодом, — у пару `program` + `comments`. Якщо розбір не вдається, зовнішнім споживачам повертається `null`, щоб сканування не падало на синтаксично проблемних файлах.
+
+Обхід дерева будується з урахуванням предків, щоб правила могли відрізняти контекст верхнього рівня від вкладеного всередині функцій. Під час такого обходу вузли-функції та виклики спискових операцій розпізнаються як типові шаблони для аналізу, а текстові фрагменти нормалізуються до компактного вигляду для повідомлень про порушення.
+
+Окремий набір хелперів працює з `TemplateLiteral`: один збирає видимий текст усіх частин без вставок, інший за цим текстом визначає, чи схоже місце на SQL-контекст зі списком значень. Це дає змогу знаходити небезпечні або підозрілі шаблони без дублювання однакової логіки в різних правилах.
+
+Для аналізу імпортів спільно використовуються перевірки на звичайний `require` і динамічний `import` з рядковим модулем. Обидва хелпери повертають лише назву модуля або порожній результат, щоб сканери могли однаково працювати з різними формами завантаження без прив’язки до конкретного правила.
+
+Усі операції побудовані fail-safe: помилки парсингу або несподівані вузли не пробиваються назовні, а переводяться в безпечний результат. Це дозволяє сканерам пропускати проблемні фрагменти й продовжувати перевірку решти коду.
 
 ## Публічний API
 
-- langFromPath — Визначає мову Oxc на основі розширення файлу.
-- offsetToLine — Перетворює зміщення в буфер на номер рядка.
-- normalizeSnippet — Форматує текст повідомлення про порушення, видаляючи зайві пробіли.
-- isFunctionNode — Визначає, чи є вузол у абстрактному синтаксичному дереві (AST) функцією.
-- walkAstWithAncestors — Рекурсивно обходить AST, враховуючи контекст (чи знаходиться вузол всередині функції).
-- parseProgramOrNull — Парсить файл та повертає AST, якщо успішно, або `null` у разі помилки.
-- parseProgramAndCommentsOrNull — Парсить файл та повертає об'єкт з AST та коментарями, або `null` у разі помилки.
-- isJoinCall — Визначає, чи є виклик `.join` (для динамічних списків SQL).
-- templateQuasisText — Витягує текст з `quasis` у `TemplateLiteral`, ігноруючи вирази.
-- isSqlListContextTemplate — Визначає, чи є `TemplateLiteral` контекстом SQL-списку (наприклад, `IN` або `VALUES`).
-- requireCallModule — Перевіряє, чи є виклик `require` з рядковим ім'ям.
+- langFromPath — Мова для Oxc за шляхом файлу (розширення).
+- offsetToLine — Номер рядка (1-based) за зміщенням у буфері.
+- normalizeSnippet — Стискає пробіли для повідомлення про порушення.
+- isFunctionNode — Чи є вузол функцією.
+- walkAstWithAncestors — Рекурсивний обхід AST з предками, щоб визначати контекст (всередині функції чи ні).
+- parseProgramOrNull — Парсить файл і повертає `program` або null, якщо є синтаксичні помилки чи виняток.
+- parseProgramAndCommentsOrNull — Парсить файл і повертає `{ program, comments }` або null. Окремий вхід для перевірок,
+яким потрібні коментарі (наприклад, маркер `// n-rules:allow-unsafe: ...` біля виклику) —
+базовий `parseProgramOrNull` свідомо лишається без коментарів, щоб не змінювати API.
+- isJoinCall — Чи це `.join(...)` виклик (типово для динамічних списків у SQL).
+- templateQuasisText — Текст quasis у TemplateLiteral (без expressions).
+- isSqlListContextTemplate — Чи виглядає TemplateLiteral як SQL-контекст зі списком (IN/VALUES (...)).
+- requireCallModule — Перевіряє, чи це виклик `require('<module>')` з рядковим аргументом.
+Спільне для сканерів імпортів (`bunyan-imports`, `redis-imports`, ...).
+- dynamicImportModule — Перевіряє, чи це динамічний `import('<module>')` з рядковим аргументом.
+Спільне для сканерів імпортів.
 
 ## Гарантії поведінки
 
-- `langFromPath` повертає назву мови JavaScript або TypeScript на основі розширення файлу.
-- `langFromPath` повертає `null`, якщо розширення файлу не підтримується.
-- `offsetToLine` перетворює зміщення в коді на номер рядка.
-- `offsetToLine` повертає `null`, якщо зміщення недійсне.
-- `normalizeSnippet` стискає текст сніпета.
-- `normalizeSnippet` повертає `null`, якщо не вдалося стиснути сніпет.
-- `isFunctionNode` визначає, чи є вузол AST функцією.
-- `isFunctionNode` повертає `true` якщо вузол є функцією, інакше `false`.
-- `walkAstWithAncestors` обходить AST, враховуючи предки вузлів.
-- `walkAstWithAncestors` не повертає значень.
-- `parseProgramOrNull` парсує програму та повертає її як AST або `null`, якщо парсинг не вдається.
-- `parseProgramOrNull` повертає `null`, якщо програма не може бути успішно розпарсена.
-- `parseProgramAndCommentsOrNull` парсує програму
+- Власних операцій запису (ФС/БД) у файлі немає; виклики імпортованих модулів можуть писати.
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).
+- За певних помилок повертає порожнє значення (напр. `null`) замість винятку.