@nitra/cursor 3.22.0 → 3.23.1

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

@@ -0,0 +1,175 @@
+# check-reporter.mjs
+
+## Огляд
+
+Модуль `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/discover-check-rules-from-cursor.md

@@ -0,0 +1,157 @@
+# discover-check-rules-from-cursor.mjs
+
+## Огляд
+
+Модуль `discover-check-rules-from-cursor.mjs` визначає, які саме id правил повинні бути запущені командою `npx @nitra/cursor fix`, коли користувач викликає її **без аргументів**. Він узгоджує два джерела:
+
+1. **Файлова система проєкту** — базові імена `*.mdc` у директорії `.cursor/rules/` (тобто правила, які реально присутні у конкретному репо).
+2. **Реєстр пакета** — список id правил, для яких у пакеті `@nitra/cursor` існує programmatic перевірка (JS-концерн або policy з `target.json`); цей список зазвичай приходить із функції `discoverCheckableRules`.
+
+Результат — впорядкований унікальний масив id, у якому:
+
+- порядок диктується порядком файлів `*.mdc` у директорії правил (як їх передали ззовні, зазвичай відсортованими);
+- залишаються лише ті id, для яких у пакеті є реальна перевірка;
+- видалено префікс `n-`, оскільки внутрішня команда `check <id>` оперує «короткими» id (наприклад, `bun`, а не `n-bun`).
+
+Файл містить чисті pure-функції без побічних ефектів — без `fs`, без `process`, без I/O. Все читання директорії правил і реєстру здійснюється викликачем; цей модуль лише поєднує два готових списки.
+
+## Експорти / API
+
+Модуль має три публічних експорти у форматі ES modules (`.mjs`):
+
+| Експорт                             | Тип        | Призначення                                                                                      |
+| ----------------------------------- | ---------- | ------------------------------------------------------------------------------------------------ |
+| `MANAGED_RULE_FILE_PREFIX`          | `string`   | Константа `'n-'` — префікс імен файлів `.mdc`, які вважаються «керованими» пакетом.              |
+| `mdcBasenameToCheckId`              | `function` | Перетворює базове ім'я `*.mdc` (із розширенням або без) у id для CLI-команди `check`.            |
+| `discoverCheckRulesFromCursorRules` | `function` | Будує впорядкований список id перевірок як перетин «доступних у пакеті» та «присутніх на диску». |
+
+Усі експорти — іменовані (`export const` / `export function`); default-export відсутній.
+
+## Функції
+
+### `mdcBasenameToCheckId(mdcBasename)`
+
+**Сигнатура:**
+
+```js
+export function mdcBasenameToCheckId(mdcBasename: string): string
+```
+
+**Параметри:**
+
+- `mdcBasename` — рядок, який може бути:
+  - чистим базовим іменем файлу, наприклад `'n-bun.mdc'` або `'my-rule.mdc'`;
+  - відносним/абсолютним шляхом, наприклад `'.cursor/rules/n-bun.mdc'` (функція сама візьме сегмент після останнього `/`).
+
+**Поведінка:**
+
+1. Якщо у вхідному рядку є символ `/`, береться підрядок після останнього `/` — таким чином приймаються як «чисті» імена, так і шляхи.
+2. Якщо отриманий рядок закінчується на `.mdc`, розширення відсікається.
+3. Якщо те, що залишилось, починається з `MANAGED_RULE_FILE_PREFIX` (`'n-'`), цей префікс також знімається.
+4. Повертається отриманий «короткий» id.
+
+**Повертає:**
+
+- `string` — id, придатний для команди `check <id>`. Приклади:
+  - `'n-bun.mdc'` → `'bun'`
+  - `'.cursor/rules/n-vue.mdc'` → `'vue'`
+  - `'my-rule.mdc'` → `'my-rule'`
+  - `'n-text'` (без розширення) → `'text'`
+
+**Side effects:** немає. Функція суто детермінована, не звертається до файлової системи, не мутує аргументи.
+
+**Крайні випадки:**
+
+- Backslashes (`\\`) як роздільник шляху **не** розпізнаються — функція оперує лише `/`. Це безпечно для шляхів, які прийшли від утиліт на кшталт `fs.readdir`, що повертають базові імена, або з `path.posix`-стилю.
+- Якщо вхід уже без `.mdc`, він обробляється тим самим алгоритмом (просто пропускається крок зняття розширення).
+- Якщо файл, прибравши `.mdc`, дорівнює саме `'n-'`, повернеться порожній рядок — це не очікувана реальна ситуація, бо керованих правил із порожнім id не буває.
+
+### `discoverCheckRulesFromCursorRules(available, mdcBasenames)`
+
+**Сигнатура:**
+
+```js
+export function discoverCheckRulesFromCursorRules(
+  available: string[],
+  mdcBasenames: string[],
+): string[]
+```
+
+**Параметри:**
+
+- `available` — масив id, які пакет уміє перевіряти (програмні перевірки JS-концерну або policy з `target.json`). Зазвичай — результат `discoverCheckableRules` із сусіднього модуля `discover-checkable-rules.mjs`. Очікується алфавітний порядок, але алгоритм не залежить від нього.
+- `mdcBasenames` — масив базових імен файлів `*.mdc`, які реально присутні у `.cursor/rules/` поточного проєкту. Очікується, що масив уже відсортований викликачем (порядок цього масиву визначає порядок результату).
+
+**Поведінка:**
+
+1. Створюється `Set` `seen` для дедуплікації результату.
+2. Створюється масив `ordered` для збереження порядку входу `mdcBasenames`.
+3. Для кожного `basename`:
+   - обчислюється id через `mdcBasenameToCheckId(basename)`;
+   - якщо id присутній у `available` **і** ще не доданий — додається в `ordered` та позначається у `seen`.
+4. Повертається `ordered`.
+
+**Повертає:**
+
+- `string[]` — впорядкований масив унікальних id перевірок:
+  - **тільки** ті, що одночасно (а) мають programmatic-перевірку в пакеті і (б) представлені файлом `*.mdc` у `.cursor/rules/`;
+  - порядок диктується `mdcBasenames` (тобто реальним порядком файлів у директорії, як його передав викликач);
+  - кожен id зустрічається не більше одного разу.
+
+**Side effects:** немає. Функція pure, не читає диск, не мутує аргументи (`Set`/`Array` створюються локально).
+
+**Крайні випадки:**
+
+- Якщо `mdcBasenames` порожній — повертається `[]`.
+- Якщо жоден `id`, отриманий з імен `.mdc`, не присутній у `available` — повертається `[]` (типово для проєктів, де `.cursor/rules/` містить лише сторонні правила без programmatic-перевірок у пакеті).
+- Дублікати у `mdcBasenames` (наприклад, два файли, що дають один і той самий id після відсікання префікса) включаються лише один раз.
+
+## Залежності
+
+- **Зовнішні (npm/Node):** немає. Файл не використовує жодних імпортів — ні з Node core (`fs`, `path` тощо), ні з npm-пакетів.
+- **Внутрішні (проєкт):** немає прямих імпортів. Очікується, що:
+  - аргумент `available` формується сусіднім модулем `discover-checkable-rules.mjs` (експорт `discoverCheckableRules`);
+  - аргумент `mdcBasenames` формується викликачем читанням `.cursor/rules/` (через `fs.readdirSync`/`fs.promises.readdir` із подальшим фільтром `.endsWith('.mdc')` та сортуванням).
+
+Така архітектура свідомо відокремлює I/O від чистої логіки: цей модуль легко тестувати без файлової системи.
+
+## Потік виконання / Використання
+
+Типовий сценарій — `npx @nitra/cursor fix` без аргументів. CLI-входу потрібно вирішити, які id перевірок запустити за замовчуванням; для цього він:
+
+1. Отримує список програмно перевірюваних правил пакета (`available = discoverCheckableRules(...)`).
+2. Читає директорію `.cursor/rules/` поточного проєкту й відбирає файли з розширенням `.mdc` (`mdcBasenames`), сортує їх.
+3. Викликає `discoverCheckRulesFromCursorRules(available, mdcBasenames)` і отримує **підсумковий** список id.
+4. Для кожного id послідовно запускає команду `check <id>` (наприклад, через `run-rule-cli.mjs`).
+
+Приклад інлайн-використання (псевдокод викликача):
+
+```js
+import { readdirSync } from 'node:fs'
+import { discoverCheckableRules } from './discover-checkable-rules.mjs'
+import { discoverCheckRulesFromCursorRules } from './discover-check-rules-from-cursor.mjs'
+
+const available = discoverCheckableRules(/* … */)
+const mdcBasenames = readdirSync('.cursor/rules')
+  .filter(f => f.endsWith('.mdc'))
+  .sort()
+const idsToRun = discoverCheckRulesFromCursorRules(available, mdcBasenames)
+// idsToRun: наприклад, ['adr', 'bun', 'ci4', 'text', 'vue']
+```
+
+Приклад трансформації імен:
+
+| Файл у `.cursor/rules/`    | id після `mdcBasenameToCheckId` | Потрапляє у результат?                             |
+| -------------------------- | ------------------------------- | -------------------------------------------------- |
+| `n-bun.mdc`                | `bun`                           | Так, якщо `available.includes('bun')`              |
+| `n-vue.mdc`                | `vue`                           | Так, якщо `available.includes('vue')`              |
+| `my-rule.mdc`              | `my-rule`                       | Лише якщо пакет реєструє `my-rule` як перевірюване |
+| `.cursor/rules/n-text.mdc` | `text`                          | Так, якщо `available.includes('text')`             |
+| `n-bun.mdc` (двічі)        | `bun`                           | У результаті — один раз                            |
+
+Таким чином модуль є тонким, але критичним «клейовим» шаром між:
+
+- **диском проєкту** (що користувач реально хоче перевіряти, судячи з вмісту `.cursor/rules/`)
+- **реєстром пакета** (що пакет фізично вміє перевіряти автоматично).
+
+Файл свідомо тримається без I/O і без зовнішніх залежностей, щоб залишатись повністю детермінованим і легко покритим юніт-тестами (див. сусідню директорію `tests/`).

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

@@ -0,0 +1,165 @@
+# discover-checkable-rules.mjs
+
+## Огляд
+
+Модуль `discover-checkable-rules.mjs` — це discovery-шар для CLI-команди `fix`. Його завдання — швидко просканувати файлову структуру каталогу `npm/rules/` та виявити «прогонні» правила, тобто правила, у яких є щонайменше один JS-концерн або policy-концерн. Правила, які складаються тільки з декларативних артефактів (`.mdc` + `auto.md`) без жодного прогонного концерну, відсіюються.
+
+Виокремлюються два типи концернів:
+
+- **JS concerns** — окремі файли `rules/<id>/js/<concern>.mjs`. Кожен файл — один концерн (flat-конвенція).
+- **Policy concerns** — підкаталоги `rules/<id>/policy/<concern>/`, у яких присутній файл `target.json` (поруч із якого зазвичай лежить `<concern>.rego`).
+
+Модуль свідомо не парсить вміст `target.json` і не читає JS-файли — це лише швидкий «структурний» скан (шляхи + назви) без I/O-вмісту. Парсинг покладено на runner.
+
+Файли-помічники з префіксом `_` (зокрема каталог `_lib/`), тестові файли `*.test.mjs`, а також приховані файли/каталоги (`.`-префікс) ігноруються.
+
+Історичний контекст конвенції розкладки JS-концернів:
+
+- `js/<concern>/check.mjs` — версії 1.13.80–1.13.89 (вкладений каталог на концерн);
+- `js/<concern>.mjs` — версії 1.13.90+ (flat: концерн = файл, а не каталог).
+
+Допоміжні файли, тести, шаблони й дані винесені в окремі топ-level папки правила: `js/_lib/`, `tests/`, `templates/`, `data/`.
+
+## Експорти / API
+
+Модуль експортує дві асинхронні функції:
+
+| Експорт                                   | Тип                                                | Призначення                                                                                    |
+| ----------------------------------------- | -------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
+| `discoverOneRule(ruleDir, ruleId)`        | `async (string, string) => Promise<CheckableRule>` | Будує опис одного правила за заданим шляхом каталогу та id, без обходу `rules/`.               |
+| `discoverCheckableRules(bundledRulesDir)` | `async (string) => Promise<CheckableRule[]>`       | Сканує цілий каталог `npm/rules/` і повертає масив правил, для яких є JS- або policy-концерни. |
+
+Внутрішніми (не експортованими) залишаються функції `listJsConcerns` і `listPolicyConcerns`.
+
+### Типи (JSDoc `@typedef`)
+
+```text
+JsConcern        { name: string }                                  // basename файла js/<name>.mjs без розширення
+PolicyConcern    { name: string }                                  // imʼя підкаталогу policy/<name>/
+CheckableRule    {
+                   id: string,                                     // = basename каталогу rules/<id>/
+                   jsConcerns: JsConcern[],                        // алфавітно
+                   policyConcerns: PolicyConcern[],                // алфавітно
+                 }
+```
+
+## Функції
+
+### `listJsConcerns(jsDir)` (internal)
+
+- **Сигнатура:** `async function listJsConcerns(jsDir: string): Promise<JsConcern[]>`
+- **Параметри:**
+  - `jsDir` — абсолютний шлях до каталогу `rules/<id>/js/`.
+- **Повертає:** масив `JsConcern[]`, відсортований алфавітно за `name` через `Array.prototype.toSorted` із компаратором `localeCompare`.
+- **Логіка:**
+  1. Якщо каталог `jsDir` не існує (`existsSync` повертає `false`) — повертається `[]`.
+  2. Читається вміст через `readdir(jsDir, { withFileTypes: true })` — тобто отримуються `Dirent`-обʼєкти з метаінформацією.
+  3. Пропускаються:
+     - сутності, що не є файлом (`!entry.isFile()`);
+     - файли без розширення `.mjs`;
+     - тестові файли `*.test.mjs`;
+     - службові файли з префіксом `_` (наприклад вміст `_lib/`, хоча сам `_lib` як каталог не буде файлом і відсіється раніше);
+     - приховані файли з префіксом `.`.
+  4. Для решти файлів обчислюється `name = entry.name.slice(0, -'.mjs'.length)` — basename без розширення.
+- **Side effects:** лише файлові читання (`existsSync`, `readdir`), без запису.
+
+### `listPolicyConcerns(policyDir)` (internal)
+
+- **Сигнатура:** `async function listPolicyConcerns(policyDir: string): Promise<PolicyConcern[]>`
+- **Параметри:**
+  - `policyDir` — абсолютний шлях до каталогу `rules/<id>/policy/`.
+- **Повертає:** масив `PolicyConcern[]`, відсортований алфавітно за `name`.
+- **Логіка:**
+  1. Якщо `policyDir` не існує — повертається `[]`.
+  2. Читається вміст з `withFileTypes: true`.
+  3. Пропускаються будь-які записи, що не є каталогом, а також приховані каталоги (префікс `.`).
+  4. Для кожного підкаталогу перевіряється наявність файла `target.json` через `existsSync(join(policyDir, entry.name, 'target.json'))`. Якщо `target.json` є — підкаталог зараховується як policy-концерн.
+- **Side effects:** лише файлові читання, без запису.
+
+### `discoverOneRule(ruleDir, ruleId)` (exported)
+
+- **Сигнатура:** `export async function discoverOneRule(ruleDir: string, ruleId: string): Promise<CheckableRule>`
+- **Параметри:**
+  - `ruleDir` — абсолютний шлях до каталогу правила `rules/<id>/`;
+  - `ruleId` — ідентифікатор правила, зазвичай `basename(ruleDir)`. Передається явно, бо функція не виводить його з шляху самостійно.
+- **Повертає:** обʼєкт `CheckableRule` з полями `id`, `jsConcerns`, `policyConcerns`. На відміну від `discoverCheckableRules`, тут не виконується фільтрація «має бути хоч щось» — повертається опис як є (можуть бути порожні масиви концернів).
+- **Логіка:** паралельно (точніше — послідовно `await`-ить) запускає `listJsConcerns(join(ruleDir, 'js'))` і `listPolicyConcerns(join(ruleDir, 'policy'))` та збирає результати в обʼєкт.
+- **Використання:** викликається `runStandardRule`-flow для per-rule entry-point, коли потрібно отримати опис конкретного правила, а не сканувати весь каталог.
+- **Side effects:** лише читання файлової системи.
+
+### `discoverCheckableRules(bundledRulesDir)` (exported)
+
+- **Сигнатура:** `export async function discoverCheckableRules(bundledRulesDir: string): Promise<CheckableRule[]>`
+- **Параметри:**
+  - `bundledRulesDir` — абсолютний шлях до кореневого каталогу всіх правил (зазвичай `npm/rules/`).
+- **Повертає:** масив `CheckableRule[]`, відсортований алфавітно за `id`. Включаються тільки правила, у яких `jsConcerns.length > 0 || policyConcerns.length > 0`.
+- **Логіка:**
+  1. Якщо `bundledRulesDir` не існує — повертається `[]`.
+  2. Читається вміст каталогу з `withFileTypes: true`.
+  3. Пропускаються сутності, які не є каталогом, та приховані каталоги (префікс `.`).
+  4. Для кожного підкаталогу формується `ruleDir = join(bundledRulesDir, entry.name)` і викликається `discoverOneRule(ruleDir, entry.name)`.
+  5. Правила, у яких немає жодного JS- або policy-концерну (декларативні-only), відсіюються.
+- **Side effects:** лише читання файлової системи (без запису, без мережевих викликів).
+
+## Залежності
+
+Виключно зовнішні стандартні модулі Node.js:
+
+- `node:fs` → `existsSync` — синхронна перевірка існування шляху;
+- `node:fs/promises` → `readdir` — асинхронне читання вмісту каталогу (з `withFileTypes: true` повертає `Dirent[]`);
+- `node:path` → `join` — кросплатформова конкатенація шляхів.
+
+Внутрішніх імпортів з інших модулів проєкту немає. Це робить модуль чистим discovery-шаром без бізнес-логіки, що дозволяє безпечно його тестувати ізольовано (потрібна лише підготовлена файлова структура у тимчасовому каталозі).
+
+Зворотні залежності (хто використовує цей модуль): runner-флоу CLI `fix` (зокрема `runStandardRule`), який після discovery читає `target.json` для policy-концернів і виконує JS-концерни.
+
+## Потік виконання / Використання
+
+### Типовий сценарій 1. Повний скан правил для CLI `fix`
+
+```javascript
+import { discoverCheckableRules } from './discover-checkable-rules.mjs'
+
+const rules = await discoverCheckableRules('/abs/path/to/npm/rules')
+for (const rule of rules) {
+  // rule.id, rule.jsConcerns, rule.policyConcerns
+}
+```
+
+Послідовність дій усередині:
+
+1. `discoverCheckableRules` перевіряє існування кореневого каталогу.
+2. Перебирає підкаталоги верхнього рівня (= потенційні правила).
+3. Для кожного підкаталогу викликає `discoverOneRule`, який своєю чергою:
+   - сканує `rules/<id>/js/` через `listJsConcerns`;
+   - сканує `rules/<id>/policy/` через `listPolicyConcerns`;
+4. Якщо знайдено хоч один концерн — правило додається у вихідний масив.
+5. Масив сортується за `id`.
+
+### Типовий сценарій 2. Per-rule entry-point
+
+```javascript
+import { discoverOneRule } from './discover-checkable-rules.mjs'
+
+const rule = await discoverOneRule('/abs/path/to/npm/rules/n-js-lint', 'n-js-lint')
+// rule.id === 'n-js-lint'
+// rule.jsConcerns — список JS-концернів у js/
+// rule.policyConcerns — список policy-концернів у policy/
+```
+
+Цей шлях оминає енумерацію всього `rules/`, що корисно коли id правила вже відомий (наприклад, передано аргументом CLI).
+
+### Гарантії та обмеження
+
+- **Чистота:** функції — read-only (не пишуть у ФС, не виконують код концернів). Це дозволяє безпечно викликати їх повторно.
+- **Сортування:** усі результати алфавітно відсортовані через `toSorted` із `localeCompare`. Це робить вивід детермінованим між запусками й між платформами (хоч порядок `readdir` залежить від ФС).
+- **Толерантність до відсутніх каталогів:** будь-яка з директорій (`rules/`, `js/`, `policy/`) може бути відсутня — повертається порожній масив без помилки.
+- **Тести/хелпери:** файли з префіксом `_` і `*.test.mjs` гарантовано виключаються із JS-концернів.
+- **Що _не_ робиться:** не валідуються імена концернів, не парситься `target.json`, не перевіряється наявність `<name>.rego` поруч із `target.json`. Це робота runner-а.
+
+### Eage cases
+
+- Файл з префіксом `.` у `js/` — пропускається.
+- Підкаталог у `js/` (наприклад `_lib/`) — не є файлом, відсіюється першою перевіркою `entry.isFile()`.
+- Підкаталог у `policy/` без `target.json` — пропускається; наявність `<name>.rego` без `target.json` не зараховується.
+- Порожнє правило (тільки `.mdc`/`auto.md` без `js/` і `policy/`) — не потрапляє у вихід `discoverCheckableRules`, але буде повернене з порожніми масивами в `discoverOneRule`.