@nitra/cursor 3.21.1 → 3.23.0

package/scripts/lib/docs/check-mdc-template-refs.md

@@ -0,0 +1,222 @@
+# check-mdc-template-refs.mjs
+
+## Огляд
+
+Модуль `check-mdc-template-refs.mjs` — це невелика утиліта, призначена для перевірки цілісності посилань між файлом правила `<id>.mdc` та шаблонами, що лежать у підкаталогах `template/` цього самого правила. Він обходить структуру каталогів правила (`fix/<concern>/template/`, `policy/<concern>/template/`), збирає всі знайдені файли й порівнює їхні відносні шляхи з вмістом основного файлу правила `<id>.mdc`. Результатом є перелік шаблонних файлів, на які у `.mdc` немає жодного markdown-посилання, тобто «осиротілі» (orphaned) шаблони.
+
+Типовий контекст застосування: модуль використовується в утилітах перевірки/лінтингу правил репозиторію (`npm/rules/<id>/`), де `.mdc`-файл описує правило людською мовою й має посилатися на свої шаблони. Якщо шаблон існує, але не згаданий у `.mdc`, цей модуль повідомить про нього, щоб супровідник правила або додав посилання, або видалив зайвий шаблон.
+
+Модуль повністю асинхронний (використовує `node:fs/promises`), стандартної залежності від сторонніх бібліотек не має, працює у середовищі Node.js (а також сумісне з Bun) як ES-модуль (`.mjs`).
+
+## Експорти / API
+
+Модуль експортує єдину функцію:
+
+- `findMissingMdcRefs(ruleDir, ruleId)` — публічний експорт (`export async function`).
+
+Дві внутрішні (не експортовані) допоміжні функції:
+
+- `walkTemplateDirs(ruleDir)` — обходить підкаталоги `fix/*/template/` і `policy/*/template/`.
+- `collectFiles(dir)` — рекурсивно збирає всі файли в заданому каталозі.
+
+Імпорти з ядра Node:
+
+- `existsSync` з `node:fs` — синхронна перевірка існування шляху.
+- `readdir`, `readFile`, `stat` з `node:fs/promises` — асинхронні операції з файловою системою.
+- `join`, `relative` з `node:path` — нормалізація та побудова шляхів.
+
+## Функції
+
+### findMissingMdcRefs
+
+Сигнатура:
+
+```
+export async function findMissingMdcRefs(ruleDir, ruleId): Promise<string[]>
+```
+
+Параметри:
+
+- `ruleDir` — `string`, абсолютний шлях до каталогу правила (за конвенцією `npm/rules/<id>/`).
+- `ruleId` — `string`, basename правила (наприклад, `"security"`). Використовується для побудови імені `.mdc`-файлу: `${ruleId}.mdc`.
+
+Що робить:
+
+1. Будує очікуваний шлях до файлу правила: `mdcPath = join(ruleDir, `${ruleId}.mdc`)`.
+2. Якщо файл `.mdc` не існує — повертає порожній масив `[]` (нічого перевіряти).
+3. Читає текст `.mdc` у пам'ять як UTF-8 рядок.
+4. Викликає `walkTemplateDirs(ruleDir)`, щоб отримати масив усіх файлів із `template/`-каталогів правила (як шляхи, відносні до `ruleDir`).
+5. Фільтрує отриманий масив, залишаючи лише ті файли, посилань на які НЕ виявлено в тексті `.mdc`. Перевірка наявності посилання — підрядкова: файл вважається «посиланим», якщо в тексті `.mdc` зустрічається будь-яке з двох вкраплень:
+   - `./<rel>` — типова форма markdown-посилання `[label](./path)`.
+   - `(<rel>)` — також зловить голу форму `(path)` у круглих дужках.
+
+Повертає:
+
+- `Promise<string[]>` — масив відносних шляхів (відносно `ruleDir`) файлів шаблонів, на які в `.mdc` немає посилання.
+
+Side effects:
+
+- Виключно read-only доступ до файлової системи: `existsSync`, `readFile`, `readdir`, `stat`. Файли або каталоги не створюються, не змінюються, не видаляються.
+- Не виводить нічого в `stdout`/`stderr`. Не має побічних ефектів на process state.
+
+Помилки:
+
+- Може кинути помилку, якщо `readFile`/`readdir`/`stat` зазнають невдачі з причин, відмінних від «файл не існує» (наприклад, права доступу). Перед читанням існування `mdcPath` перевіряється явно, тому відсутність `.mdc` помилки не дає.
+
+### walkTemplateDirs (внутрішня)
+
+Сигнатура:
+
+```
+async function walkTemplateDirs(ruleDir): Promise<string[]>
+```
+
+Параметри:
+
+- `ruleDir` — `string`, абсолютний шлях до каталогу правила.
+
+Що робить:
+
+1. Ітерується по двох жорстко закодованих «kind»-категоріях: `'fix'` та `'policy'`.
+2. Для кожного `kind` будує шлях `kindDir = join(ruleDir, kind)`. Якщо такого каталогу немає — пропускає.
+3. Для кожного `concern` (підкаталога або файлу всередині `kindDir`, який повертає `readdir`) будує шлях `tpl = join(kindDir, concern, 'template')`.
+4. Якщо `tpl` не існує — пропускає. Якщо існує, але не є каталогом (`stat(tpl).isDirectory() === false`) — також пропускає.
+5. Викликає `collectFiles(tpl)` для рекурсивного збору всіх файлів і додає їх до результуючого масиву.
+6. На виході перетворює абсолютні шляхи у шляхи, відносні до `ruleDir` (`relative(ruleDir, p)`).
+
+Повертає:
+
+- `Promise<string[]>` — відносні (від `ruleDir`) шляхи всіх файлів у `fix/*/template/` і `policy/*/template/`.
+
+Side effects:
+
+- Лише read-only ФС-операції.
+
+Примітка: значення `readdir(kindDir)` (без `withFileTypes`) повертає масив імен і файлів, і каталогів. Перевірка `existsSync(tpl)` та `stat(tpl).isDirectory()` коректно відсіює випадки, коли `concern` — це файл, а не каталог.
+
+### collectFiles (внутрішня)
+
+Сигнатура:
+
+```
+async function collectFiles(dir): Promise<string[]>
+```
+
+Параметри:
+
+- `dir` — `string`, абсолютний шлях каталогу, який треба обійти.
+
+Що робить:
+
+1. Викликає `readdir(dir, { withFileTypes: true })` і отримує `Dirent[]`.
+2. Для кожного запису будує повний шлях `full = join(dir, entry.name)`.
+3. Якщо запис — каталог (`entry.isDirectory()`), рекурсивно занурюється в нього й приєднує знайдене до результату.
+4. Якщо запис — файл (або symlink/інше, що НЕ каталог), додає `full` як є.
+
+Повертає:
+
+- `Promise<string[]>` — абсолютні шляхи всіх файлів усередині `dir` (з усіх рівнів вкладеності).
+
+Side effects:
+
+- Read-only обхід ФС.
+
+Зауваження щодо поведінки: символьні посилання й сокети не каталогізуються як директорії (`isDirectory()` поверне `false`), отже потрапляють у список як «файли». Гранична глибина рекурсії не обмежена — для зацикленої структури symlinks теоретично можливе нескінченне занурення; на практиці шаблонні каталоги правил такого не мають.
+
+## Залежності
+
+Стандартна бібліотека Node.js (ESM):
+
+- `node:fs` — `existsSync` (синхронна перевірка існування).
+- `node:fs/promises` — `readdir`, `readFile`, `stat` (асинхронні ФС-операції).
+- `node:path` — `join`, `relative` (нормалізація шляхів).
+
+Зовнішніх npm-залежностей немає. Модуль не використовує жодних глобальних змінних, конфігів, env-vars чи CLI-аргументів. Не звертається до мережі.
+
+Передумови оточення:
+
+- Node.js версія, що підтримує ES Modules (`.mjs`) і `node:`-protocol-imports (Node 14+; на практиці Node 18+/Bun).
+- Доступ на читання до каталогу `ruleDir` та його підкаталогів.
+
+## Потік виконання / Використання
+
+### Очікувана структура каталогу правила
+
+Модуль розрахований на конвенцію розкладки правил:
+
+```
+<ruleDir>/
+  <ruleId>.mdc                 ← текст правила з markdown-посиланнями
+  fix/
+    <concern-A>/
+      template/
+        file1.ext
+        nested/file2.ext
+    <concern-B>/
+      template/
+        ...
+  policy/
+    <concern-C>/
+      template/
+        ...
+```
+
+Перелічуються лише файли всередині `fix/*/template/` і `policy/*/template/`. Будь-який інший контент (`check-*.mjs`, `README`, інші підкаталоги) ігнорується.
+
+### Алгоритм у двох словах
+
+1. Зібрати всі файли з `fix/*/template/` і `policy/*/template/`, перетворити у відносні шляхи від `ruleDir`.
+2. Прочитати `<ruleId>.mdc`.
+3. Для кожного відносного шляху перевірити, чи зустрічається в тексті `.mdc` хоча б одна з форм `./<rel>` або `(<rel>)`. Якщо НЕ зустрічається — додати у вихідний список.
+
+### Типове використання
+
+```js
+import { findMissingMdcRefs } from './check-mdc-template-refs.mjs'
+
+const missing = await findMissingMdcRefs('/abs/path/to/npm/rules/security', 'security')
+if (missing.length > 0) {
+  console.error('Orphaned template files (no markdown link in .mdc):')
+  for (const rel of missing) console.error(`  - ${rel}`)
+  process.exit(1)
+}
+```
+
+Цей виклик часто є частиною check-скрипта правила (`check-<id>.mjs`) або агрегованого валідатора, який обходить усі правила репозиторію.
+
+### Граничні випадки
+
+- `.mdc` відсутній — повертається `[]`. Це навмисно: правило без `.mdc` не валідуємо «на покинуті шаблони».
+- Каталоги `fix/`, `policy/`, `template/` відсутні — обходяться silent, результат для них порожній.
+- Шаблонів немає взагалі — повертається `[]`.
+- `.mdc` посилається на шаблон, якого фізично немає, — цей сценарій модуль НЕ перевіряє (зворотний напрям перевірки тут не реалізовано).
+- Перевірка посилань — підрядкова, без парсингу markdown. Якщо файл містить `./foo/bar.md` як випадковий збіг у документації, шаблон `foo/bar.md` буде вважатися посиланим, навіть якщо це не власне markdown-link. На практиці це не проблема, бо шляхи всередині `template/` достатньо унікальні.
+- Сепаратор шляхів — платформозалежний (`path.join`/`path.relative` використовують `\` на Windows). Усередині `.mdc` посилання, як правило, пишуть зі слешем `/` — на Windows це може давати хибно-позитивні результати (тобто файл буде вважатися «без посилання»). У цільовому оточенні (macOS/Linux/Docker) проблема не виникає.
+
+### Складність
+
+- Час: O(N + M), де N — сумарна кількість файлів у `template/`-каталогах, а M — довжина тексту `.mdc` (через `String.prototype.includes`, що виконується для кожного з N файлів двічі).
+- Пам'ять: лінійна щодо розміру `.mdc` плюс масиву шляхів.
+
+## Rebuild Test
+
+Файл `check-mdc-template-refs.mjs` можна повністю відновити, дотримуючись опису вище, якщо забезпечити такі властивості:
+
+1. ES-модуль (`.mjs`), без `default export`. Єдиний `export` — `async function findMissingMdcRefs(ruleDir, ruleId)`.
+2. Імпорти лише з `node:fs` (`existsSync`), `node:fs/promises` (`readdir`, `readFile`, `stat`) і `node:path` (`join`, `relative`).
+3. Дві внутрішні async-функції: `walkTemplateDirs(ruleDir)` та `collectFiles(dir)`.
+4. `walkTemplateDirs` ітерується по двох категоріях у фіксованому порядку: спочатку `'fix'`, потім `'policy'`. Пропускає неіснуючі `kindDir`. Для кожного `concern` перевіряє існування й те, що `template` — каталог; у разі успіху делегує до `collectFiles`. На виході конвертує абсолютні шляхи у відносні від `ruleDir`.
+5. `collectFiles` використовує `readdir(dir, { withFileTypes: true })`, рекурсивно занурюється тільки в каталоги, інші записи додає в результат як абсолютні шляхи.
+6. `findMissingMdcRefs` спочатку перевіряє існування `<ruleId>.mdc`, читає його у UTF-8, отримує всі файли через `walkTemplateDirs`, потім фільтрує, залишаючи лише ті `rel`, для яких у тексті `.mdc` ОДНОЧАСНО немає `./<rel>` і немає `(<rel>)` (логічне AND через подвійне заперечення з `||` під `!`).
+7. Поведінка строго read-only: жодних запитів у мережу, жодного запису на диск, жодного консольного виводу.
+8. Повертає `Promise<string[]>`, відносні шляхи (з POSIX/платформозалежним сепаратором у міру `path.relative`).
+
+Тестові сценарії для smoke-перевірки:
+
+- Каталог без `.mdc` → `[]`.
+- `.mdc` є, але `fix/`, `policy/` відсутні → `[]`.
+- `fix/x/template/a.txt` існує, у `.mdc` згадано `./fix/x/template/a.txt` → `[]`.
+- Той самий шаблон, але `.mdc` посилається як `(fix/x/template/a.txt)` (без `./`) → `[]`.
+- Той самий шаблон, але в `.mdc` посилання немає → `['fix/x/template/a.txt']`.
+- Вкладений `fix/x/template/sub/b.txt`, посилання немає → містить `'fix/x/template/sub/b.txt'`.
+- Запис `concern`, що насправді є файлом, а не каталогом → пропускається без помилки.

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/`).