@7n/rules 1.0.0

package/scripts/lib/docs/changed-files.md

@@ -0,0 +1,32 @@
+---
+type: JS Module
+title: changed-files.mjs
+resource: npm/scripts/lib/changed-files.mjs
+docgen:
+  crc: 792d3942
+  score: 100
+---
+
+Файл збирає змінені та незакомічені файли з робочого дерева. Визначає базовий комміт для перевірок у межах зміненого діапазону. Збирає змінені та незакомічені файли відносно базового комміту.
+
+## Поведінка
+
+collectChangedFiles Збирає змінені та незакомічені файли з робочого дерева.
+resolveChangedBase Визначає базовий комміт для scoped-перевірок.
+collectChangedFilesSince Збирає змінені та незакомічені файли відносно базового комміту.
+
+## Публічний API
+
+- collectChangedFiles: Збирає список змінених та невідстежених файлів з робочого дерева відносно робочого дерева.
+- resolveChangedBase: Визначає базовий комміт для обмежених перевірок без використання зовнішнього стану.
+  - Пріоритет: локальна `main`, потім `origin/main`.
+  - Якщо обидві відсутні, повертає null, і викликаючий порівнює лише робоче дерево з HEAD.
+- collectChangedFilesSince: Збирає список змінених та невідстежених файлів відносно базового комміту.
+- git diff <base>: Порівнює комміт `base` з поточним робочим деревом (включаючи закомічені та незакомічені модифікації).
+  - Якщо `base` відсутній, використовується `collectChangedFiles`.
+
+## Гарантії поведінки
+
+- Read-only: файл не виконує операцій запису у файлову систему.
+- За невдачі повертає значення помилки (`false`/`null`/`Err`) замість генерування винятку чи паніки.
+- Не звертається до мережі.

package/scripts/lib/docs/check-reporter.md

@@ -0,0 +1,179 @@
+---
+type: JS Module
+title: check-reporter.mjs
+resource: npm/scripts/lib/check-reporter.mjs
+docgen:
+  crc: b76ed480
+---
+
+Модуль `check-reporter.mjs` — це невелика спільна (shared) бібліотека-фабрика для check-скриптів (`check-*.mjs`) і для `lint-docker`. Вона надає уніфікований спосіб репортити результати перевірок: успіхи (`pass`) та помилки (`fail`), а також акумулювати фінальний код виходу процесу (`exit code`).
+
+Основна ідея: викликаючи фабрику `createCheckReporter()`, споживач отримує об’єкт з трьома методами — `pass`, `fail` і `getExitCode`. Будь-який виклик `fail` переводить внутрішній лічильник у стан помилки (`exitCode = 1`), і подальший `getExitCode()` повертатиме `1`. Якщо `fail` жодного разу не викликали — `getExitCode()` поверне `0`.
+
+Модуль навмисно тримає API мінімальним і не нав’язує конкретний формат виводу: рядок успіху форматується делегованою функцією `pass` з `../utils/pass.mjs`, а помилка виводиться у форматі `  ❌ <msg>` через `console.log`.
+
+Важлива поведінкова деталь: `getExitCode` — це **метод-геттер у вигляді функції**, а не геттер-властивість через `get`. Тому слід викликати саме `reporter.getExitCode()` у момент завершення, а не деструктурувати `const { exitCode } = reporter` — інакше отримаєш undefined або застаріле значення, оскільки `exitCode` як поле в об’єкті не експонується назовні (це замикання).
+
+## Експорти / API
+
+Модуль експортує одну іменовану (named) функцію:
+
+- `createCheckReporter()` — фабрика, що повертає об’єкт-репортер.
+
+Структура об’єкта, який повертає `createCheckReporter()`:
+
+| Поле          | Тип                     | Опис                                                                                               |
+| ------------- | ----------------------- | -------------------------------------------------------------------------------------------------- |
+| `pass`        | `typeof pass`           | Реекспорт функції `pass` з `../utils/pass.mjs`. Друкує рядок успіху у форматі, визначеному `pass`. |
+| `fail`        | `(msg: string) => void` | Друкує рядок помилки з префіксом ` ❌` і виставляє внутрішній `exitCode = 1`.                      |
+| `getExitCode` | `() => number`          | Повертає `0`, якщо `fail` жодного разу не викликали, інакше `1`.                                   |
+
+JSDoc-сигнатура у файлі:
+
+```js
+/**
+ * @returns {{
+ *   pass: typeof pass,
+ *   fail: (msg: string) => void,
+ *   getExitCode: () => number
+ * }}
+ */
+```
+
+## Функції
+
+### `createCheckReporter()`
+
+**Сигнатура:**
+
+```js
+export function createCheckReporter(): {
+  pass: typeof pass,
+  fail: (msg: string) => void,
+  getExitCode: () => number,
+}
+```
+
+**Параметри:** немає.
+
+**Повертає:** новий об’єкт-репортер з трьома методами. Кожен виклик `createCheckReporter()` створює **окреме замикання** з власним внутрішнім `exitCode`, тобто різні репортери незалежні один від одного.
+
+**Side effects:** при створенні — жодних. Side effects виникають лише при виклику методів повернутого об’єкта (`fail` пише в stdout через `console.log`; `pass` робить те, що визначено в `../utils/pass.mjs`).
+
+**Внутрішня логіка:**
+
+1. Створюється локальна змінна `let exitCode = 0`.
+2. Повертається об’єктний літерал з трьома методами:
+   - `pass` — пряма посилання на імпортовану функцію `pass`.
+   - `fail(msg)` — виконує `console.log(\` ❌ ${msg}\`)`і присвоює`exitCode = 1`.
+   - `getExitCode()` — повертає поточне значення `exitCode`.
+
+### Метод `pass` (повертається з фабрики)
+
+**Сигнатура:** успадковує сигнатуру функції `pass` з `../utils/pass.mjs` (`typeof pass`).
+
+**Поведінка:** повний контракт — за `../utils/pass.mjs`. У межах цього модуля `pass` просто реекспортується без обгортки і не впливає на `exitCode`.
+
+### Метод `fail(msg)` (повертається з фабрики)
+
+**Сигнатура:**
+
+```js
+fail(msg: string): void
+```
+
+**Параметри:**
+
+- `msg: string` — текст повідомлення про помилку.
+
+**Повертає:** `undefined`.
+
+**Side effects:**
+
+- Пише в stdout рядок виду `  ❌ <msg>` через `console.log` (два пробіли індентації + хрестик-емодзі + пробіл + повідомлення).
+- Виставляє внутрішній `exitCode = 1` у замиканні фабрики.
+
+**Семантика:** після першого виклику `fail` репортер «фіксує» загальний стан як помилковий — це безповоротна операція в межах одного інстансу.
+
+### Метод `getExitCode()` (повертається з фабрики)
+
+**Сигнатура:**
+
+```js
+getExitCode(): number
+```
+
+**Параметри:** немає.
+
+**Повертає:** `0` (якщо `fail` не викликали жодного разу) або `1` (якщо викликали хоча б один раз).
+
+**Side effects:** немає.
+
+**Чому функція, а не властивість:** значення `exitCode` зберігається в замиканні. Звичайне поле об’єкта закарбувало б початкове `0` і не відображало б подальших змін. Геттер-функція забезпечує «живе» зчитування актуального стану.
+
+## Залежності
+
+### Внутрішні (з репо)
+
+- `../utils/pass.mjs` — імпортується named-імпорт `pass`. Це функція, що друкує рядок успіху в уніфікованому форматі. Для деталей формату див. документацію `pass.mjs`.
+
+### Зовнішні (Node/runtime)
+
+- Глобальний `console.log` — для виводу помилок у `fail()`.
+
+### Без побічних залежностей
+
+Модуль чистий від npm-пакетів, не звертається до файлової системи, мережі чи `process.exit` — повернений `getExitCode()` лише **повідомляє** код, але **не завершує** процес самостійно. Завершення процесу — відповідальність викликаючого скрипта.
+
+## Потік виконання / Використання
+
+### Типовий сценарій у check-скрипті
+
+```js
+import { createCheckReporter } from '../lib/check-reporter.mjs'
+
+const reporter = createCheckReporter()
+
+if (somethingWrong) {
+  reporter.fail('Опис проблеми')
+} else {
+  reporter.pass('Усе ок')
+}
+
+// Важливо: викликати getExitCode() саме як функцію
+process.exit(reporter.getExitCode())
+// або: return reporter.getExitCode()
+```
+
+### Як використовується в `lint-docker` та інших споживачах
+
+Один інстанс `reporter` створюється на запуск перевірки. У циклі по ресурсах (файлах, правилах, конфігах тощо) виконуються виклики `pass` / `fail` залежно від результату. По завершенні — одноразовий `getExitCode()`, значення якого передається в `process.exit(...)` або повертається з `async`-функції-точки входу.
+
+### Антипатерн (нерекомендовано)
+
+```js
+// ❌ НЕ робити так — exitCode не «знімається» цим способом,
+// бо це не геттер-властивість, а замикання поверх локальної змінної.
+const { exitCode } = reporter
+process.exit(exitCode) // буде undefined
+```
+
+Правильно:
+
+```js
+process.exit(reporter.getExitCode())
+```
+
+### Семантика exit code
+
+- `0` — усі перевірки пройшли (або жодного `fail` не було).
+- `1` — щонайменше один `fail`. Подальші виклики `fail` не «накопичують» вище 1 — це бінарний прапорець «була помилка / не було».
+
+### Формат виводу
+
+- Успіх: формат повністю делегований `pass` з `../utils/pass.mjs`.
+- Помилка: `  ❌ <msg>` (два пробіли + ❌ + пробіл + повідомлення), завжди через `console.log` (stdout, з переведенням рядка).
+
+### Ізольованість інстансів
+
+Кожен виклик `createCheckReporter()` повертає новий незалежний об’єкт із власним `exitCode`. Це означає, що в одному процесі можна тримати кілька паралельних/незалежних репортерів — наприклад, по одному на правило/секцію — і агрегувати їхні фінальні коди вручну (через `Math.max` чи логічне OR), якщо потрібно.

package/scripts/lib/docs/collect-test-files.md

@@ -0,0 +1,32 @@
+---
+type: JS Module
+title: collect-test-files.mjs
+resource: npm/scripts/lib/collect-test-files.mjs
+docgen:
+  crc: d4b01600
+  model: openai-codex/gpt-5.4-mini
+  tier: cloud-min
+  score: 100
+  issues: judge:inaccurate:0.98
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+## Огляд
+
+Спільна логіка для `test/no-*`-концернів, що сканують `*.test.{mjs,js}`. Вона обходить дерево з урахуванням ignore-правил із `.n-rules.json`, визначає тестові файли, а для звітів уніфікує їхні шляхи до відносного POSIX-формату. Компонент read-only: не виконує записів у ФС чи БД.
+
+## Поведінка
+
+- **isTestFile** — визначає, чи шлях вказує на JS-тестовий файл із суфіксом `.test.mjs` або `.test.js`.
+- **collectTestFiles** — збирає всі такі тестові файли в дереві репозиторію, враховуючи ігнорування з `.n-rules.json`.
+- **toRelPosix** — перетворює абсолютний шлях на відносний до кореня репозиторію у POSIX-форматі для уніфікованих повідомлень.
+
+## Публічний API
+
+- isTestFile — Визначає, чи шлях веде до JS test-файла з розширенням `*.test.mjs` або `*.test.js`.
+- collectTestFiles — Знаходить у `cwd` усі файли `*.test.{mjs,js}`, пропускаючи те, що відфільтровано через `.n-rules.json`.
+- toPosixRel — Перетворює шлях файлу від `cwd` у posix-формат для єдиного виду повідомлень про порушення.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).

package/scripts/lib/docs/concern-meta.md

@@ -0,0 +1,34 @@
+---
+type: JS Module
+title: concern-meta.mjs
+resource: npm/scripts/lib/concern-meta.mjs
+docgen:
+  crc: 85be92d0
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  tier: local-min
+  score: 100
+  issues: judge:inaccurate:0.97
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+## Огляд
+
+Цей модуль зчитує та валідує схему конфігурації, визначену у `concern.json`. Він надає функції для отримання метаданих concern-ів та списку доступних concern-ів. Модуль працює в режимі fail-safe: при виявленні помилок він не генерує винятків, а повертає `null` замість них.
+
+## Поведінка
+
+Поведінка
+readConcernMeta зчитує і перевіряє файл concern.json у вказаній директорії concern-а, повертаючи метадані або null, якщо файл відсутній чи не валідний.
+listConcerns сканує директорію правил і повертає список усіх знайдених concern-ів у алфавітному порядку, ігноруючи каталоги без concern.json.
+Нормалізований meta несе `fixability` (`code`|`config`|`structural`); невідоме/відсутнє значення зводиться до `code` — дефолт, за яким concern лишається eligible для LLM-fix-ladder.
+
+## Публічний API
+
+readConcernMeta — Зчитує та уніфікує налаштування з `concern.json` у каталозі; повертає відсутність або недійсність.
+listConcerns — Повертає список усіх визначених concern-ів з підкаталогів `ruleDir` у алфавітному порядку, ігноруючи каталоги без `concern.json`.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).
+- За певних помилок повертає порожнє значення (напр. `null`) замість винятку.

package/scripts/lib/docs/diff-added-lines.md

@@ -0,0 +1,38 @@
+---
+type: JS Module
+title: diff-added-lines.mjs
+resource: npm/scripts/lib/diff-added-lines.mjs
+docgen:
+  crc: 4913e63d
+---
+
+Файл визначає, чи є рядок коду новим (introduced) або вже існував у проєкті. Він використовується для класифікації результатів аналізу коду (lint-findings) на основі їхнього розташування відносно версії проєкту. Це допомагає розробникам розуміти, які зміни коду потребують негайної уваги.
+
+## Поведінка
+
+ALL_LINES: мітка, що позначає всі рядки файлу, які були introduced.
+parseAddedLines: парсить вивід `git diff` та повертає мапу, де ключ — ім'я файлу, а значення — множина номерів рядків, які були додані.
+addedLinesByFile: визначає мапу доданих рядків для заданих файлів, використовуючи `git diff` та `git ls-files`.
+isIntroducedLine: перевіряє, чи рядок у файлі є introduced, використовуючи мапу, створену `addedLinesByFile`.
+
+## Публічний API
+
+- ALL_LINES — Вказує на новий, не відстежений файл, що містить усі рядки.
+- parseAddedLines — Аналізує вивід команди `git diff --unified=0` для створення мапи доданих рядків у файлі.
+- addedLinesByFile — Визначає додані рядки у файлах, порівнюючи їх з версією в HEAD, та класифікує їх як відстежені або не відстежені.
+- isIntroducedLine — Перевіряє, чи рядок у файлі є новим, тобто доданим.
+
+## Гарантії поведінки
+
+- `ALL_LINES` повертає список усіх рядків файлу.
+- `ALL_LINES` повертає `false` якщо не вдалося парсити diff.
+- `parseAddedLines` повертає список рядків, які були додані у diff.
+- `parseAddedLines` повертає `false` якщо не вдалося парсити diff.
+- `addedLinesByFile` повертає список рядків, які були додані у кожному файлі.
+- `isIntroducedLine` визначає, чи є рядок доданим у diff.
+- `isIntroducedLine` повертає `false` якщо рядок не був доданий у diff.
+- Результати парсингу кешуються для кожного запуску.
+- Рядок вважається "introduced" якщо він є в diff.
+- Рядок вважається "pre-existing" якщо він не є в diff.
+- Рядки, що не були знайдені в diff, вважаються "untracked".
+- `ALL_LINES` повертає всі рядки з diff, навіть якщо вони "untracked".

package/scripts/lib/docs/discover-check-rules-from-cursor.md

@@ -0,0 +1,29 @@
+---
+type: JS Module
+title: discover-check-rules-from-cursor.mjs
+resource: npm/scripts/lib/discover-check-rules-from-cursor.mjs
+docgen:
+  crc: 622756ba
+  score: 100
+---
+
+Файл зчитує базові імена файлів `.mdc` у директорії `.cursor/rules/` та генерує список ідентифікаторів правил для `npx @7n/rules fix`, використовуючи перевірку через JS-концерн або policy з `target.json`.
+
+## Поведінка
+
+MANAGED_RULE_FILE_PREFIX Визначає префікс керованих правил пакета у файлах `.cursor/rules/`.
+
+mdcBasenameToCheckId Перетворює базове ім'я `.mdc` у id правила для `check <id>`.
+
+discoverCheckRulesFromCursorRules Будує впорядкований список id перевірок за файлами правил на диску, фільтруючи їх за наявністю у доступних перевірок.
+
+## Публічний API
+
+MANAGED_RULE_FILE_PREFIX — визначає префікс для керованих правил у директорії `.cursor/rules/`.
+mdcBasenameToCheckId — трансформує базове ім'я файлу `.mdc` у ідентифікатор правила для функції `check`.
+discoverCheckRulesFromCursorRules — створює відсортований список ідентифікаторів перевірок на основі файлів правил з курсору.
+
+## Гарантії поведінки
+
+- Read-only: файл не виконує операцій запису у файлову систему.
+- Не звертається до мережі.

package/scripts/lib/docs/discover-checkable-rules.md

@@ -0,0 +1,25 @@
+---
+type: JS Module
+title: discover-checkable-rules.mjs
+resource: npm/scripts/lib/discover-checkable-rules.mjs
+docgen:
+  crc: 5c278c6f
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+---
+
+Визначає наявність JS-концернів та policy-концернів у заданому каталозі правила. Сканує всі каталоги правил, шукаючи JS-концерни у файлах `rules/<id>/js/<concern>.mjs` та policy-концерни, що асоціюються з парою `<concern>.rego` та `target.json`. Повертає список правил, які містять такі прогонні частини. Файли з префіксом `_` або `*.test.mjs` ігноруються.
+
+## Поведінка
+
+discoverOneRule описує правило, виявляючи JS-концерни та policy-концерни в заданому каталозі правила.
+discoverCheckableRules сканує каталог правил і повертає список правил, які мають JS-концерни або policy-концерни, фільтруючи ті, що не мають прогонних частин.
+
+## Публічний API
+
+- discoverOneRule — Створює об'єкт для одного правила, що перевіряє конкретний каталог.
+- discoverCheckableRules — Знаходить правила у каталозі `rules/`, які мають відповідні скрипти (у `js/`) або політики (у `policy/`). Ігнорує правила, що містять лише документацію.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).

package/scripts/lib/docs/ensure-tool.md

@@ -0,0 +1,258 @@
+---
+type: JS Module
+title: ensure-tool.mjs
+resource: npm/scripts/lib/ensure-tool.mjs
+docgen:
+  crc: 42b0cd01
+---
+
+Модуль `ensure-tool.mjs` — єдина точка резолву зовнішніх CLI-залежностей пакета `@7n/rules`. Він гарантує, що потрібний бінарник (`hk`, `conftest`, `shellcheck`, `actionlint`, `dotenv-linter`, `opa`, `regal`, `hadolint`, `kubeconform`, `kubescape`) доступний у системі, виконуючи послідовний пошук:
+
+1. У системному `PATH` (через `resolveCmd`).
+2. У керованому кеші бінарників (`~/.cache/@7n/rules/bin/` на Linux/macOS або `%LOCALAPPDATA%\@nitra\cursor\bin\` на Windows).
+3. Авто-встановлення відповідно до OS (`brew` для macOS, `scoop` для Windows із fallback на GitHub Release, прямий завантажувач GitHub Release для Linux).
+4. Hard-fail з персоналізованою підказкою, якщо авто-встановлення вимкнено змінною середовища `N_CURSOR_NO_AUTO_INSTALL`.
+
+Така архітектура усуває дублювання install-логіки в кожному `lint.mjs` / `fix.mjs`: щоб додати нову зовнішню утиліту, достатньо одного запису в реєстрі `TOOLS`. Додатково модуль експортує `ensureHkInstall`, який реєструє git pre-commit hook через `hk install` (пропускається в CI).
+
+Файл написаний для Node.js (ESM), використовує лише стандартну бібліотеку та один локальний хелпер `resolveCmd`.
+
+## Експорти / API
+
+| Експорт                  | Тип        | Призначення                                                                                                    |
+| ------------------------ | ---------- | -------------------------------------------------------------------------------------------------------------- |
+| `ensureTool(toolId)`     | `function` | Резолвить і за потреби встановлює зовнішній CLI. Повертає абсолютний шлях до бінарника або кидає `Error`.      |
+| `ensureHkInstall(hkBin)` | `function` | Виконує `hk install` для реєстрації git pre-commit hook. Жодного return value; на помилку лише `console.warn`. |
+
+Внутрішні (не експортуються, але формують контракт модуля):
+
+- `TOOLS` — реєстр `Record<string, ToolEntry>` із описом install-стратегії для кожного тула.
+- `ToolEntry` — JSDoc-тип, що описує поля одного запису реєстру.
+- Допоміжні функції: `getCacheDir`, `mapArch`, `fetchLatestVersion`, `installFromGithub`, `installViaBrew`, `installViaScoop`, `autoInstall`, `buildHint`.
+
+## Функції
+
+### `getCacheDir()`
+
+- **Сигнатура:** `getCacheDir(): string`
+- **Параметри:** немає.
+- **Повертає:** абсолютний шлях до каталогу кешу бінарників.
+- **Логіка:**
+  - На `win32` бере `process.env.LOCALAPPDATA` (fallback `homedir()/AppData/Local`) і додає `@7n/rules/bin`.
+  - На інших платформах повертає `homedir()/.cache/@7n/rules/bin`.
+- **Side effects:** немає (тільки читає env / `os.homedir`).
+
+### `mapArch(nodeArch, style)`
+
+- **Сигнатура:** `mapArch(nodeArch: 'x64'|'arm64'|string, style: 'hk'|'conftest'|'actionlint'): string`
+- **Параметри:**
+  - `nodeArch` — значення `process.arch`.
+  - `style` — стиль іменування платформи для release-asset:
+    - `'actionlint'` → `amd64` / `arm64`.
+    - `'conftest'` → `x86_64` / `arm64`.
+    - `'hk'` (та інші release-asset стилі: shellcheck, dotenv-linter) → `x86_64` / `aarch64`.
+- **Повертає:** рядок архітектури, очікуваний у назві release-asset.
+- **Side effects:** немає.
+
+### `fetchLatestVersion(repo, curlBin)`
+
+- **Сигнатура:** `fetchLatestVersion(repo: string, curlBin: string): string`
+- **Параметри:**
+  - `repo` — репозиторій у форматі `owner/repo`.
+  - `curlBin` — абсолютний шлях до бінарника `curl`.
+- **Повертає:** версію останнього релізу без префікса `v` (наприклад `0.4.1`).
+- **Поведінка:** через `spawnSync` викликає `curl -sSL -H "Accept: application/vnd.github+json" https://api.github.com/repos/<repo>/releases/latest`, парсить JSON, бере поле `tag_name`, прибирає префікс `v` за допомогою регексу `TAG_V_PREFIX_RE`.
+- **Помилки:**
+  - `curl failed: ...` — `r.error` ненульове.
+  - `curl exit <status>: ...` — ненульовий exit-код.
+  - `GitHub API response is not JSON: ...` — некоректний JSON.
+  - `GitHub API: tag_name missing for <repo>` — у відповіді немає `tag_name`.
+- **Side effects:** мережевий HTTP-запит до GitHub API.
+
+### `installFromGithub(toolId, entry, cacheDir)`
+
+- **Сигнатура:** `installFromGithub(toolId: string, entry: ToolEntry, cacheDir: string): string`
+- **Параметри:**
+  - `toolId` — ключ у `TOOLS`.
+  - `entry` — `ToolEntry` для цього тула.
+  - `cacheDir` — абсолютний шлях до каталогу кешу.
+- **Повертає:** абсолютний шлях до встановленого бінарника.
+- **Послідовність дій:**
+  1. Резолвить `curl` та `tar` у PATH; за відсутності — кидає `Error`.
+  2. Через `fetchLatestVersion` отримує актуальну версію.
+  3. Формує назву asset через `entry.asset(ver)` і URL `https://github.com/<github>/releases/download/v<ver>/<asset>`.
+  4. Створює `cacheDir` (`mkdirSync` з `recursive: true`).
+  5. Завантажує asset через `curl -sSL -o <archivePath> <downloadUrl>`.
+  6. Якщо `entry.archive === false` — перейменовує завантажений файл у `<cacheDir>/<toolId>`, виставляє права `0o755` і повертає шлях.
+  7. Інакше викликає `tar` із прапорцем `-xJf` (для `.tar.xz`) або `-xzf` (для `.tar.gz`) для розпакування в `cacheDir`.
+  8. Визначає реальний шлях до бінарника через `entry.binFinder(ver)` або просто `toolId`. Перевіряє існування файлу.
+  9. Опціонально видаляє завантажений архів через `rm` (м’яко: якщо `rm` не знайдено, продовжує).
+- **Помилки:**
+  - `curl не знайдено в PATH — потрібен для завантаження <toolId>`.
+  - `tar не знайдено в PATH — потрібен для встановлення <toolId>`.
+  - `Завантаження <toolId> не вдалось: ...` / `curl exit <status> при завантаженні <toolId>: ...`.
+  - `tar failed for <toolId>: ...` / `tar exit <status> для <toolId>: ...`.
+  - `Бінарник <toolId> не знайдено після розпакування: <binPath>`.
+- **Side effects:** мережа, файлова система (створення/перейменування файлів, chmod, видалення архіву).
+
+### `installViaBrew(toolId, entry)`
+
+- **Сигнатура:** `installViaBrew(toolId: string, entry: ToolEntry): string`
+- **Параметри:** `toolId` і `entry` як у попередній функції.
+- **Повертає:** абсолютний шлях до бінарника після встановлення (через повторний `resolveCmd(toolId)`).
+- **Послідовність дій:**
+  1. Резолвить `brew` у PATH; на відсутність кидає `brew не знайдено в PATH. Встанови Homebrew: https://brew.sh`.
+  2. Виконує `brew install <entry.brew>` із `stdio: 'inherit'` (інтерактивний прогрес).
+  3. Перевіряє exit-код і `error` об’єкт.
+  4. Після успіху повторно резолвить `toolId` у PATH; якщо й тоді нема — кидає `... не знайдено в PATH після brew install`.
+- **Side effects:** виклик зовнішнього `brew install` (мережа, мутація системного стану на macOS).
+
+### `installViaScoop(toolId, entry)`
+
+- **Сигнатура:** `installViaScoop(toolId: string, entry: ToolEntry): string`
+- **Параметри:** як вище.
+- **Повертає:** абсолютний шлях до бінарника після встановлення.
+- **Поведінка:** дзеркало `installViaBrew`, але для `scoop install`.
+  - Якщо `entry.scoop === null` — кидає `... недоступний у Scoop. Встанови вручну: https://github.com/<repo>/releases`.
+  - Якщо `scoop` не у PATH — кидає `scoop не знайдено в PATH. Встанови Scoop: https://scoop.sh`.
+- **Side effects:** виклик зовнішнього `scoop install`.
+
+### `autoInstall(toolId, entry, cacheDir)`
+
+- **Сигнатура:** `autoInstall(toolId: string, entry: ToolEntry, cacheDir: string): string`
+- **Поведінка диспетчера за платформою:**
+  - `darwin` → `installViaBrew`.
+  - `win32` → пробує `installViaScoop`, на будь-який throw — fallback на `installFromGithub` (наприклад, для `dotenv-linter` чи `regal`, де `scoop: null`).
+  - Інше (Linux) → `installFromGithub`.
+- **Повертає:** абсолютний шлях до бінарника.
+- **Side effects:** делегує своїм внутрішнім installer-ам.
+
+### `buildHint(toolId, entry)`
+
+- **Сигнатура:** `buildHint(toolId: string, entry: ToolEntry): string`
+- **Параметри:** як вище.
+- **Повертає:** багаторядкове повідомлення для error message при заблокованому авто-installі.
+- **Формат:**
+  - Перший рядок — `❌ <toolId> не знайдено в PATH і авто-встановлення відключено (N_CURSOR_NO_AUTO_INSTALL).`.
+  - Другий рядок — `   Встанови:`.
+  - Далі — OS-specific підказка:
+    - macOS: `     macOS: brew install <entry.brew>`.
+    - Windows: `     Windows: scoop install <entry.scoop>` (якщо доступний) та `     або: https://github.com/<repo>/releases`.
+    - Linux: `     Linux: https://github.com/<repo>/releases`.
+- **Side effects:** немає.
+
+### `ensureTool(toolId)` _(export)_
+
+- **Сигнатура:** `ensureTool(toolId: string): string`
+- **Параметри:** `toolId` — ключ у реєстрі `TOOLS` (`'hk'`, `'conftest'`, `'shellcheck'`, `'actionlint'`, `'dotenv-linter'`, `'opa'`, `'regal'`, `'hadolint'`, `'kubeconform'`, `'kubescape'`).
+- **Повертає:** абсолютний шлях до бінарника.
+- **Послідовність резолву:**
+  1. **Валідація** — якщо `TOOLS[toolId]` відсутній, кидає `ensureTool: невідомий тул '<toolId>'`.
+  2. **PATH** — `resolveCmd(toolId)`; якщо знайдено — повертає одразу.
+  3. **Кеш** — `join(getCacheDir(), toolId)`; якщо файл існує — повертає його шлях. Зауваження: перевірка спрощена і не враховує `entry.binFinder` (для cached binaries `installFromGithub` уже клав фінальний бінарник у відоме місце або кеш просто не містить такого файлу — у такому разі переходимо до install).
+  4. **Авто-install** — якщо змінна середовища `N_CURSOR_NO_AUTO_INSTALL` не виставлена, викликає `autoInstall(toolId, entry, cacheDir)`.
+  5. **Hard-fail** — кидає `Error(buildHint(toolId, entry))`.
+- **Помилки:** будь-яка з помилок `autoInstall` / `installFrom*` піднімається вгору; додатково — `невідомий тул` та `❌ ... не знайдено в PATH`.
+- **Side effects:** мережа, файлова система, виклик зовнішніх install-команд (`brew`, `scoop`, `curl`, `tar`, `rm`).
+
+### `ensureHkInstall(hkBin)` _(export)_
+
+- **Сигнатура:** `ensureHkInstall(hkBin: string): void`
+- **Параметри:**
+  - `hkBin` — абсолютний шлях до бінарника `hk` (зазвичай отриманий через `ensureTool('hk')`).
+- **Повертає:** `void`.
+- **Логіка:**
+  - Якщо `process.env.CI` truthy — функція виходить без дії (не реєструємо hook у CI).
+  - Інакше виконує `spawnSync(hkBin, ['install'], { stdio: 'inherit' })`.
+  - На `r.error` або ненульовий `r.status` виводить попередження через `console.warn` (не кидає!).
+- **Side effects:** запис git pre-commit hook у `.git/hooks/pre-commit` (через `hk`), вивід у stdout/stderr.
+
+## Залежності
+
+### Стандартна бібліотека Node.js
+
+- `node:child_process` — `spawnSync` для синхронного запуску `curl`, `tar`, `brew`, `scoop`, `rm`, `hk`.
+- `node:fs` — `chmodSync`, `existsSync`, `mkdirSync`, `renameSync`.
+- `node:os` — `homedir` для побудови шляху кешу.
+- `node:path` — `join` для конструювання шляхів.
+- `node:process` — `arch`, `env`, `platform`.
+
+### Внутрішні
+
+- `../utils/resolve-cmd.mjs` → `resolveCmd(cmd)` — кросплатформне резолвлення абсолютного шляху до бінарника в PATH (Linux/macOS — like `which`, Windows — like `where`).
+
+### Зовнішні CLI (виконуються через `spawnSync`)
+
+- `curl` — завантаження GitHub API і release-asset.
+- `tar` — розпакування `.tar.gz` / `.tar.xz`.
+- `rm` — м’яке видалення завантаженого архіву (необов’язково).
+- `brew` — install на macOS.
+- `scoop` — install на Windows.
+- `hk` — реєстрація git pre-commit hook у `ensureHkInstall`.
+
+### Змінні середовища
+
+- `N_CURSOR_NO_AUTO_INSTALL` — якщо встановлена, блокує авто-install і змушує `ensureTool` кидати помилку з install-hint.
+- `CI` — якщо truthy, `ensureHkInstall` нічого не робить.
+- `LOCALAPPDATA` (Windows) — використовується для побудови шляху кешу.
+
+## Потік виконання / Використання
+
+### Типовий сценарій `ensureTool('shellcheck')` на Linux x64
+
+1. Викликається `ensureTool('shellcheck')`.
+2. `resolveCmd('shellcheck')` — не знайдено в `PATH`.
+3. `getCacheDir()` повертає `/home/<user>/.cache/@7n/rules/bin`.
+4. Перевірка `/home/<user>/.cache/@7n/rules/bin/shellcheck` — не існує.
+5. `N_CURSOR_NO_AUTO_INSTALL` не виставлено → `autoInstall(...)`.
+6. На Linux диспетчер викликає `installFromGithub('shellcheck', entry, cacheDir)`:
+   - `fetchLatestVersion('koalaman/shellcheck', curl)` → наприклад `0.10.0`.
+   - asset name = `shellcheck-v0.10.0.linux.x86_64.tar.xz`.
+   - URL = `https://github.com/koalaman/shellcheck/releases/download/v0.10.0/<asset>`.
+   - `mkdirSync(cacheDir, { recursive: true })`.
+   - `curl -sSL -o <cacheDir>/<asset> <url>`.
+   - `tar -xJf <asset> -C <cacheDir>` (бо `.tar.xz`).
+   - `binFinder('0.10.0')` → `shellcheck-v0.10.0/shellcheck`.
+   - Перевірка `existsSync(<cacheDir>/shellcheck-v0.10.0/shellcheck)`.
+   - `rm <archivePath>`.
+   - Повертає `<cacheDir>/shellcheck-v0.10.0/shellcheck`.
+7. Викликач отримує абсолютний шлях і запускає `spawnSync(bin, [...args])`.
+
+### Сценарій блокування авто-installу
+
+```js
+process.env.N_CURSOR_NO_AUTO_INSTALL = '1'
+ensureTool('hk')
+// throws Error із багаторядковим hint, наприклад на macOS:
+// ❌ hk не знайдено в PATH і авто-встановлення відключено (N_CURSOR_NO_AUTO_INSTALL).
+//    Встанови:
+//      macOS: brew install hk
+```
+
+### Сценарій реєстрації git hook
+
+```js
+import { ensureTool, ensureHkInstall } from './lib/ensure-tool.mjs'
+
+const hkBin = ensureTool('hk') // PATH → кеш → brew/scoop/github
+ensureHkInstall(hkBin) // git hook у .git/hooks/pre-commit
+```
+
+У CI (`process.env.CI=true`) другий виклик стає no-op, що зручно для pipeline-ів, де hooks не потрібні.
+
+### Розширення реєстру
+
+Щоб додати новий тул `foo`:
+
+1. Підбрати `brew`-формулу та `scoop`-пакет (або `null`, якщо відсутній).
+2. Знайти GitHub-репо релізів і визначити `archStyle` (`hk` / `conftest` / `actionlint`).
+3. Описати `asset(ver)` та, якщо потрібно, `binFinder(ver)` (коли бінарник лежить не в корені архіву).
+4. Виставити `archive: false` для прямого бінарника без архіву.
+5. Додати запис у `TOOLS`. Жодних змін у викликачах не потрібно — `ensureTool('foo')` запрацює одразу.
+
+### Гарантії та інваріанти
+
+- **Ідемпотентність:** повторний виклик `ensureTool` повертає шлях за O(1) після першого install — спочатку PATH, потім кеш.
+- **Hard-fail:** на будь-яку нерозв’язну помилку install кидається `Error` із описовим повідомленням; немає silent fallback на «обірваний» бінарник.
+- **Кросплатформність:** єдиний публічний API для трьох ОС; OS-specific деталі інкапсульовані всередині модуля.
+- **Безпека для CI:** `ensureHkInstall` ніколи не змінює git-репозиторій під CI, навіть якщо `hk` доступний.