@7n/rules 1.42.0 → 1.43.1

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## [1.43.1] - 2026-07-22
+
+### Fixed
+
+- Storybook (правило `storybook`): виправлення хвилі 2a за результатами живого пілота app-скафолда на `gt`. (1) `.storybook/main.js` app-варіанту більше НЕ знімає `vite-plugin-pages` у `viteFinal` — знімання ламало `storybook build` глобально через непідтримуваний `<route lang="yaml">`-блок (`scaffold/template/app-main.js`, `APP_MAIN_JS_MARKERS`). (2) Storybook vitest-проєкт app-пакетів отримує ВЛАСНІ `quasar()`/`AutoImport()`/`Pages()`-плагіни замість успадкованого урізаного unit-конфіга (нові `vitest-config/template/app-storybook-project-entry.js` і `vitest.config.app.baseline.mjs`, type-aware вибір у `fix-vitest-config.mjs`, нові маркер-перевірки в `main.mjs`/`adopt/main.mjs`). (3) `storybook/hygiene` (undeclared-import і sass-variables) тепер перевіряє лише `type: 'library'` пакети — на app-пакетах давав хибні спрацювання на Vite `resolve.alias`-специфікаторах і на свідомо відсутньому `sassVariables`-маркері app-`main.js`. (4) Додано канонічний шаблон `.storybook/vitest.setup.js` (стандартний `@storybook/addon-vitest`-boilerplate) — генерується/перевіряється `scaffold`-концерном для обох типів пакета. (5) `npm/schemas/n-rules.json`: додано `storybook.detectApps`/`storybook.optOut` до кореневої схеми — без цього `additionalProperties: false` відкидав ці вже задокументовані поля `.n-rules.json` як невідомі.
+
+## [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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@7n/rules",
-  "version": "1.42.0",
+  "version": "1.43.1",
   "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/schemas/n-rules.json

@@ -67,6 +67,26 @@
       "type": "boolean",
       "description": "Чи синхронізувати `.claude/settings.json` (hooks + permissions, merge зі збереженням користувацьких полів) і slash-команди checks. За замовчуванням true.",
       "default": true
+    },
+    "storybook": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Конфігурація канону Storybook (правило storybook, storybook.mdc).",
+      "properties": {
+        "detectApps": {
+          "type": "boolean",
+          "description": "Хвиля 2a: чи додавати у скоуп канону Storybook app-проєкти (vue у dependencies, не бібліотека, + src/pages/) на додачу до Vue component library пакетів хвилі 1. За замовчуванням false.",
+          "default": false
+        },
+        "optOut": {
+          "type": "array",
+          "description": "Root dir пакетів, виключених зі скоупу канону Storybook (той самий формат, що повертає workspace-роутинг — '.' для кореня, 'packages/ui' тощо).",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        }
+      }
     }
   },
   "required": [

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`) замість винятку.