@nitra/cursor 3.21.1 → 3.23.0

package/scripts/lib/docs/inline-template-links.md

@@ -0,0 +1,303 @@
+# inline-template-links.mjs
+
+## Огляд
+
+Модуль `inline-template-links.mjs` — допоміжна утиліта для **build-кроку обробки `.mdc`-правил**. Її роль: у текстовому вмісті `.mdc`-документа знайти Markdown-посилання, які ведуть на template-файли (шлях містить сегмент `/template/` або `/templates/`), і **замінити** ці посилання на **інлайн fenced-блоки** з фактичним вмістом target-файлу.
+
+Простими словами: замість того щоб у згенерованому правилі читач бачив посилання `[конфіг](./templates/package.json.snippet.json)`, він побачить безпосередньо назву реального файлу (`package.json`) і fenced-блок із його вмістом — це робить правило «самодостатнім», без потреби клікати по лінках.
+
+Особливості:
+
+- Працює асинхронно (`async`), бо читає файли через `node:fs/promises`.
+- Робить **fail-loud** валідацію: якщо посилання вказує на неіснуючий файл — кидає `Error` (а не мовчки пропускає), щоб автор правила одразу побачив проблему.
+- «Розгортає» спеціальні суфікси `.snippet.<ext>` / `.deny.<ext>` / `.contains.<ext>` до імені реального target-файлу, який вони описують (наприклад `package.json.snippet.json` → `package.json`).
+- Безпечно щодо ReDoS: усі regexp — статичні літерали з обмеженням довжини, без `new RegExp(variable)` із користувацьких даних.
+
+Модуль експортує єдину функцію `inlineTemplateLinks(text, ruleDir)`.
+
+## Експорти / API
+
+| Експорт               | Тип                                                              | Призначення                                                                                                         |
+| --------------------- | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
+| `inlineTemplateLinks` | `async function(text: string, ruleDir: string): Promise<string>` | Замінює Markdown-посилання на template-файли в `.mdc`-тексті на інлайн fenced-блоки з фактичним вмістом цих файлів. |
+
+Усі інші імена в модулі (`langFromExt`, `normalizeTargetName`, константи `MD_LINK_RE`, `TEMPLATE_SEGMENT_RE`, `SLOT_SUFFIX_RES`) — **внутрішні** (не експортуються).
+
+## Внутрішні константи
+
+### `MD_LINK_RE`
+
+```js
+;/\[([^\]]{1,200})\]\((\.\/[^)]{1,500})\)/g
+```
+
+Глобальний regexp, який ловить **Markdown-посилання вигляду `[label](./path)`** із обов'язковим префіксом `./` у href. Group 1 — текст посилання (до 200 символів), group 2 — шлях (до 500 символів, що починається з `./`). Обмеження довжин — захист від ReDoS / pathological input.
+
+### `TEMPLATE_SEGMENT_RE`
+
+```js
+;/\/templates?\//
+```
+
+Перевіряє, чи шлях містить сегмент `/template/` або `/templates/`. Тільки такі посилання вважаються «template-посиланнями» і підлягають заміні; інші Markdown-лінки залишаються недоторканими.
+
+### `SLOT_SUFFIX_RES`
+
+Масив із трьох **статичних** regexp:
+
+```js
+;[/^(.+)\.snippet\.[^.]+$/, /^(.+)\.deny\.[^.]+$/, /^(.+)\.contains\.[^.]+$/]
+```
+
+Кожен ловить ім'я файлу з суфіксом-«слотом»: `<name>.snippet.<ext>`, `<name>.deny.<ext>`, `<name>.contains.<ext>`. Group 1 — це ім'я реального target-файлу (без суфікса слоту і без власного розширення). Коментар у коді явно зазначає: regexp-літерали статичні, без `RegExp(variable)`.
+
+## Функції
+
+### `langFromExt(filePath)` — internal
+
+Сигнатура:
+
+```js
+function langFromExt(filePath: string): string
+```
+
+Параметри:
+
+- `filePath` — рядок зі шляхом до файлу (досить навіть базового імені, бо використовується лише розширення).
+
+Повертає:
+
+- Рядок-ідентифікатор мови для Markdown fenced-блока:
+  - `'json'` — якщо розширення `.json`;
+  - `'toml'` — якщо `.toml`;
+  - `'yaml'` — якщо `.yml` або `.yaml`;
+  - `''` (порожній рядок) — для будь-яких інших розширень.
+
+Side effects: жодних — чиста функція над рядком.
+
+Призначення: визначити, який мовний таг ставити після відкривального ` ``` ` у згенерованому fenced-блоці, щоб підсвічування синтаксису працювало коректно.
+
+### `normalizeTargetName(fileBasename)` — internal
+
+Сигнатура:
+
+```js
+function normalizeTargetName(fileBasename: string): string
+```
+
+Параметри:
+
+- `fileBasename` — базове ім'я файлу (без шляху), наприклад `package.json.snippet.json`.
+
+Повертає:
+
+- Якщо ім'я **збігається з одним із regexp у `SLOT_SUFFIX_RES`** (тобто має суфікс `.snippet.<ext>`, `.deny.<ext>` або `.contains.<ext>`) — повертається **group 1** першого збігу (ім'я без слоту). Приклади:
+  - `package.json.snippet.json` → `package.json`
+  - `eslint.config.js.deny.js` → `eslint.config.js`
+  - `Caddyfile.contains.txt` → `Caddyfile`
+- Якщо жоден з regexp не збігся — повертається оригінальне `fileBasename` без змін.
+
+Side effects: відсутні.
+
+Призначення: для template-файлу з суфіксом-слотом відновити **реальне ім'я target-файлу**, на який цей template посилається; саме це ім'я потім підставляється як заголовок перед fenced-блоком у згенерованому Markdown.
+
+Коментар над функцією у вихіднику прямо описує цю поведінку: «Strip `.<slot>.<ext>` suffix (slot ∈ snippet/deny/contains) to recover the real target file name».
+
+### `inlineTemplateLinks(text, ruleDir)` — **exported**
+
+Сигнатура:
+
+```js
+export async function inlineTemplateLinks(
+  text: string,
+  ruleDir: string,
+): Promise<string>
+```
+
+Параметри:
+
+- `text` — вміст `.mdc`-файлу (повний текст) як рядок.
+- `ruleDir` — **абсолютний** шлях до директорії правила (наприклад `.../npm/rules/security/`). Усі відносні href із `./` резолвляться **відносно цього каталогу**.
+
+Повертає:
+
+- `Promise<string>` — трансформований текст, у якому всі **template-посилання** замінено на блоки виду:
+
+  ````text
+  `<targetName>`:
+
+  ```<lang>
+  <contents>
+  ````
+
+  ```
+
+  де `targetName` — результат `normalizeTargetName(basename(absPath))`, `lang` — результат `langFromExt(absPath)`, а `contents` — вміст файлу після `.trim()`.
+
+  ```
+
+- Якщо у тексті немає жодного template-посилання — повертається **той самий `text` без змін** (early-exit).
+
+Алгоритм роботи:
+
+1. Знаходимо **всі** збіги `MD_LINK_RE` у `text` через `text.matchAll(...)`.
+2. Фільтруємо їх: залишаємо лише ті, у яких href (group 2) містить `/template/` або `/templates/` (через `TEMPLATE_SEGMENT_RE.test(m[2])`).
+3. Якщо після фільтрації збігів **немає** — повертаємо `text` як є.
+4. Кладемо стартовий результат `result = text`.
+5. Для кожного збігу послідовно (`for ... of`, з `await` на читанні файлу):
+   1. Деструктуруємо: `const [fullMatch, , href] = match` (label не використовується, тому позиція пропущена).
+   2. Будуємо відносний шлях: `relPath = href.slice(2)` — обрізаємо префікс `./` (його гарантує regexp).
+   3. Збираємо абсолютний шлях: `absPath = join(ruleDir, relPath)`.
+   4. Перевіряємо існування: `existsSync(absPath)`. Якщо файлу немає — **кидаємо** `Error`:
+
+      ```text
+      inlineTemplateLinks: file not found: <absPath> (referenced from .mdc)
+      ```
+
+      Жодного fallback / тихого пропуску — це fail-loud за дизайном.
+
+   5. Читаємо файл: `raw = await readFile(absPath, 'utf8')`, далі `contents = raw.trim()` (прибираємо хвостові пробіли / переноси).
+   6. Обчислюємо `lang = langFromExt(absPath)`.
+   7. Обчислюємо `targetName = normalizeTargetName(basename(absPath))`.
+   8. Формуємо `replacement` — backtick-екранований заголовок, порожній рядок і fenced-блок із `lang`:
+
+      ```js
+      ;`\`${targetName}\`:\n\n\`\`\`${lang}\n${contents}\n\`\`\``
+      ```
+
+   9. Робимо заміну: `result = result.replace(fullMatch, () => replacement)`. Передача **callback-форми** в `.replace` критично важлива: інакше спецсимволи у `replacement` (наприклад `$&`, `$1` із вмісту шаблону) трактувалися б як backreferences і зламали б вивід.
+
+6. Повертаємо `result`.
+
+Side effects:
+
+- **Читання** файлів із диска (синхронна перевірка `existsSync` + асинхронне `readFile`).
+- **Кидання `Error`** при відсутності target-файлу — це навмисна поведінка («fail loud — user must know»), а не баг.
+- Запису на диск або мережевих викликів **не робить**.
+
+Складність та обмеження:
+
+- Цикл лінійний за кількістю template-посилань у тексті; для кожного — один `existsSync` і один `readFile`.
+- Файли читаються **послідовно** (через `await` у тілі `for...of`), а не паралельно через `Promise.all`. Це осмислений вибір: правил, як правило, мало, а послідовність робить порядок помилок передбачуваним.
+- Заміна виконується через простий `result.replace(fullMatch, ...)` — перший збіг `fullMatch` у `result`. Якщо однакове Markdown-посилання трапляється кілька разів — модифікується лише перше входження (фактичний `matchAll` дасть і інші входження, але кожен з них має той самий `fullMatch`, і їх теж замінить — по одному за крок ітерації; для повних дублікатів це працює коректно).
+
+## Залежності
+
+### Стандартна бібліотека Node.js
+
+- `node:fs` → `existsSync` — синхронна перевірка наявності файлу перед читанням.
+- `node:fs/promises` → `readFile` — асинхронне читання вмісту target-файлу як UTF-8.
+- `node:path` → `basename`, `extname`, `join` — робота з шляхами:
+  - `extname` — у `langFromExt` для визначення мови;
+  - `basename` — для отримання базового імені файлу, з якого `normalizeTargetName` витягне target-ім'я;
+  - `join` — для побудови абсолютного шляху від `ruleDir` + `relPath`.
+
+### Зовнішні залежності
+
+Жодних npm-пакетів. Модуль працює лише на Node.js стандарті.
+
+### Споживачі модуля
+
+Файл лежить у `npm/scripts/lib/` поряд із іншими допоміжними утилітами для збірки правил, тому очікувані споживачі — build-скрипти у `npm/scripts/`, які генерують підсумкові `.mdc`-документи для cursor-rules / Claude-rules. Експортована функція `inlineTemplateLinks` викликається на проміжній стадії пайплайна обробки тексту `.mdc`-файлу разом із `ruleDir`, обчисленим від шляху до самого `.mdc`.
+
+## Потік виконання / Використання
+
+Типовий сценарій інтеграції в build-скрипт:
+
+```js
+import { readFile, writeFile } from 'node:fs/promises'
+import { dirname } from 'node:path'
+
+import { inlineTemplateLinks } from './lib/inline-template-links.mjs'
+
+const mdcPath = '/abs/path/to/npm/rules/security/n-security.mdc'
+const original = await readFile(mdcPath, 'utf8')
+
+const ruleDir = dirname(mdcPath) // важливо: каталог, де лежить .mdc
+const transformed = await inlineTemplateLinks(original, ruleDir)
+
+await writeFile(mdcPath, transformed, 'utf8')
+```
+
+Що відбувається крок-за-кроком на прикладі.
+
+Вхідний `.mdc`-фрагмент (`ruleDir = .../npm/rules/security/`):
+
+```text
+Snippet вимоги до `package.json` — див. [тут](./templates/package.json.snippet.json).
+```
+
+Файл `.../npm/rules/security/templates/package.json.snippet.json`:
+
+```json
+{
+  "scripts": {
+    "lint": "eslint ."
+  }
+}
+```
+
+Що зробить `inlineTemplateLinks`:
+
+1. `matchAll(MD_LINK_RE)` знайде один збіг із href `./templates/package.json.snippet.json`.
+2. `TEMPLATE_SEGMENT_RE` пропустить його (бо є `/templates/`).
+3. `relPath = 'templates/package.json.snippet.json'`, `absPath = '.../npm/rules/security/templates/package.json.snippet.json'`.
+4. `existsSync(absPath)` → `true`, файл читається.
+5. `langFromExt(absPath)` → `'json'`.
+6. `normalizeTargetName('package.json.snippet.json')` → `'package.json'` (спрацює regexp `/^(.+)\.snippet\.[^.]+$/`).
+7. `replacement` буде:
+
+   ````text
+   `package.json`:
+
+   ```json
+   {
+     "scripts": {
+       "lint": "eslint ."
+     }
+   }
+   ````
+
+   ```
+
+   ```
+
+8. Результат заміняє оригінальний Markdown-лінк у тексті.
+
+Випадки помилок:
+
+- Якщо `href` веде на неіснуючий файл — кидається `Error` із повним абсолютним шляхом у повідомленні; build-скрипт має право або впасти, або зловити цю помилку.
+- Якщо у `text` немає Markdown-посилань або жодне з них не містить `/template(s)/` — функція повертає `text` без модифікацій.
+- Якщо template-файл має нерозпізнаване розширення (наприклад `.txt` або `.conf`) — `langFromExt` поверне порожній рядок, і fenced-блок буде без мовного тегу (Markdown це допускає).
+- Якщо ім'я template-файлу **не** має одного з суфіксів `.snippet.<ext>` / `.deny.<ext>` / `.contains.<ext>` — `normalizeTargetName` поверне його як є; це нормальна поведінка для «звичайних» template-файлів, у яких саме ім'я і є target-ім'ям.
+
+## Rebuild Test
+
+Якщо видалити цей файл і відтворити його з нуля, мінімально достатній рецепт такий:
+
+1. Створи модуль `inline-template-links.mjs` у `npm/scripts/lib/`.
+2. Імпортуй з `node:fs` функцію `existsSync`, з `node:fs/promises` — `readFile`, з `node:path` — `basename`, `extname`, `join`.
+3. Оголоси константи:
+   - `MD_LINK_RE = /\[([^\]]{1,200})\]\((\.\/[^)]{1,500})\)/g` — глобальний regexp для Markdown-посилань `[label](./path)`.
+   - `TEMPLATE_SEGMENT_RE = /\/templates?\//` — фільтр шляхів, що містять `/template/` чи `/templates/`.
+   - `SLOT_SUFFIX_RES` — масив із трьох **статичних** regexp: `/^(.+)\.snippet\.[^.]+$/`, `/^(.+)\.deny\.[^.]+$/`, `/^(.+)\.contains\.[^.]+$/`. Принципово: жодного `new RegExp(variable)` — захист від ReDoS.
+4. Реалізуй `langFromExt(filePath)`:
+   - `extname(filePath)` → за вмістом повернути `'json' | 'toml' | 'yaml' | ''` (для `.yml` теж `'yaml'`).
+5. Реалізуй `normalizeTargetName(fileBasename)`:
+   - Пройди `SLOT_SUFFIX_RES` у заданому порядку; при першому збігу поверни `match[1]`. Інакше — оригінал.
+6. Експортуй `async function inlineTemplateLinks(text, ruleDir)`:
+   - `matchAll(MD_LINK_RE)` → відфільтруй за `TEMPLATE_SEGMENT_RE.test(href)`.
+   - Якщо нічого не залишилося — поверни `text`.
+   - Для кожного збігу: `relPath = href.slice(2)`, `absPath = join(ruleDir, relPath)`; якщо `!existsSync(absPath)` — `throw new Error('inlineTemplateLinks: file not found: <absPath> (referenced from .mdc)')`.
+   - Читай файл `utf8`, роби `.trim()`, обчисли `lang` і `targetName`, побудуй `replacement = \`\\\`${targetName}\\\`:\\n\\n\\\`\\\`\\\`${lang}\\n${contents}\\n\\\`\\\`\\\``.
+   - Заміни через `result = result.replace(fullMatch, () => replacement)` (саме callback-форма — щоб уникнути інтерпретації `$&`/`$1` у вмісті template-файлу).
+7. Поверни `result`.
+
+Контракт, який має зберегтися:
+
+- Чиста функція над текстом + читання файлів (без записів і без мережі).
+- **Fail-loud** на відсутній target.
+- Підтримка трьох слот-суфіксів: `snippet`, `deny`, `contains`.
+- Підтримка мов підсвічування: `json`, `toml`, `yaml`, інакше — без таргу.
+- Жодного `RegExp(variable)`.
+- Префікс href повинен починатися з `./`, інакше посилання ігнорується (це закладено в `MD_LINK_RE`).

package/scripts/lib/docs/list-rule-ids.md

@@ -0,0 +1,156 @@
+# list-rule-ids.mjs
+
+## Огляд
+
+Модуль `list-rule-ids.mjs` — невелика бібліотечна утиліта, призначена для перебору директорій-правил у каталозі `npm/rules/` та повернення відсортованого алфавітно списку ідентифікаторів правил, які реально містять виконуваний модуль `fix.mjs`.
+
+Логіка модуля побудована навколо архітектурної інваріанти проєкту: після так званої «атомарної міграції» кожне валідне правило **зобов'язане** мати файл `fix.mjs` у власній директорії `rules/<id>/`. Будь-яка піддиректорія без `fix.mjs` вважається або «не-правилом» (службова тека), або заглушкою-чернеткою — і ігнорується. Прихованих директорій (імена, що починаються з `.`) також не існує в результаті.
+
+Додатково модуль підтримує опційне точкове фільтрування одним конкретним `id`, що використовується CLI-флагом `--rule abie` для прогону команд у режимі «тільки одне правило».
+
+Модуль повністю асинхронний (використовує `node:fs/promises`), не має зовнішніх npm-залежностей і не виконує жодних побічних ефектів окрім читання директорії та перевірки наявності файлу через `existsSync`.
+
+## Експорти / API
+
+Файл експортує одну іменовану функцію:
+
+| Експорт       | Тип              | Призначення                                                                                                                       |
+| ------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| `listRuleIds` | `async function` | Повертає `Promise<string[]>` зі списком id правил, відфільтрованим за наявністю `fix.mjs` і опційним рівнянням до конкретного id. |
+
+Експорту за замовчуванням немає.
+
+## Функції
+
+### `listRuleIds(bundledRulesDir, filter)`
+
+#### Сигнатура
+
+```js
+export async function listRuleIds(bundledRulesDir, filter)
+```
+
+JSDoc-типи:
+
+```
+@param {string} bundledRulesDir — абсолютний шлях до `npm/rules/`
+@param {string} [filter]       — id одного правила (через `--rule abie`)
+@returns {Promise<string[]>}    — відсортовані алфавітно id
+```
+
+#### Параметри
+
+- **`bundledRulesDir`** (`string`, обовʼязковий) — абсолютний шлях до кореневої теки правил, найчастіше `npm/rules/` (наприклад, `/path/to/repo/npm/rules`). Передбачається, що шлях існує і є директорією; модуль не валідує його окремо — будь-яка помилка з `fs.readdir` пробрасується далі промісом.
+- **`filter`** (`string | undefined`, опційний) — точна назва правила, до якої потрібно звузити список. Якщо параметр не передано (`undefined`), повертаються всі знайдені id. Якщо передано, у результат потрапляють лише ті id, що _точно_ рівні `filter`. Часткові збіги, регулярні вирази або кейс-незалежність не підтримуються.
+
+#### Повертає
+
+`Promise<string[]>` — масив рядків-ідентифікаторів правил, відсортованих алфавітно за допомогою `Array.prototype.toSorted` із компаратором `a.localeCompare(b)`. Сортування _стабільне_ для оригінального методу і коректне для Unicode-локалей.
+
+Можливі сценарії результату:
+
+- Порожній масив `[]` — якщо в `bundledRulesDir` немає жодної директорії з `fix.mjs`, або якщо `filter` не збігається з жодним наявним id.
+- Масив з одного елемента — типово при заданому `filter`.
+- Повний відсортований список усіх правил — у випадку відсутності `filter`.
+
+#### Алгоритм / послідовність кроків
+
+1. Викликається `readdir(bundledRulesDir, { withFileTypes: true })` — отримуємо масив `Dirent`-обʼєктів (а не просто рядків імен), що дає змогу одразу перевіряти тип запису без додаткових `stat`-викликів.
+2. Залишаються лише записи, для яких одночасно:
+   - `e.isDirectory()` — це саме директорія;
+   - `!e.name.startsWith('.')` — імʼя не починається з крапки (відсікаються приховані теки на кшталт `.git`, `.cache`, тощо).
+3. Записи перетворюються на голі імена (`.map(e => e.name)`).
+4. Фільтрація на наявність `fix.mjs` — для кожного `id` синхронно перевіряється `existsSync(join(bundledRulesDir, id, 'fix.mjs'))`. Директорії без цього файлу відсіюються як «not-a-rule або заглушка».
+5. Фільтрація за `filter` — якщо параметр визначений, залишаються лише id, рівні `filter`; інакше пропускаються всі.
+6. Сортування `toSorted((a, b) => a.localeCompare(b))` — повертає новий масив без мутації проміжного.
+
+#### Side effects
+
+- **Дискові читання**: `readdir` (асинхронний обхід директорії) та `existsSync` (синхронні перевірки наявності файлу для кожного кандидата). Винятки I/O пробрасуються відхиленим промісом.
+- **Жодних записів, мережевих викликів, мутацій глобального стану, логування** — функція є read-only і чистою щодо побічних ефектів окрім згаданих читань ФС.
+- Використання `existsSync` у циклі — це _синхронні_ виклики всередині асинхронної функції; вони виконуються послідовно, але без `await`. Для типового розміру каталогу `npm/rules/` (десятки правил) це непомітна вартість.
+
+#### Гранітні випадки
+
+- Якщо `bundledRulesDir` не існує — `readdir` відхиляє проміс з `ENOENT`.
+- Якщо в директорії є символічні посилання — поведінка залежить від того, що повертає `Dirent.isDirectory()`; ця функція покладається на штатну семантику Node.js.
+- Якщо `filter` переданий як порожній рядок `''` — він _не_ є `undefined`, тому фільтр буде застосовано (`id === ''`), і результат майже напевно буде порожнім.
+- Файл `fix.mjs` як директорія: малоймовірний випадок, але `existsSync` поверне `true` для будь-якого існуючого запису з цим імʼям; модуль не розрізняє файл і теку.
+
+## Залежності
+
+### Вбудовані модулі Node.js
+
+| Модуль             | Імпортований символ | Використання                                                 |
+| ------------------ | ------------------- | ------------------------------------------------------------ |
+| `node:fs`          | `existsSync`        | Синхронна перевірка наявності `fix.mjs` у кожному кандидаті. |
+| `node:fs/promises` | `readdir`           | Асинхронний обхід `bundledRulesDir` з `withFileTypes: true`. |
+| `node:path`        | `join`              | Безпечне зʼєднання сегментів шляху до `fix.mjs`.             |
+
+### Зовнішні npm-залежності
+
+Немає.
+
+### Внутрішні залежності
+
+Файл не імпортує жодних інших модулів проєкту. Сам по собі він використовується як бібліотечна функція з інших скриптів у `npm/scripts/` (CLI-обгортки, які приймають флаг `--rule`).
+
+## Потік виконання / Використання
+
+### Контекст у проєкті
+
+`listRuleIds` — це фундамент будь-якого скрипту, який «робить щось для кожного правила»: лінт, авто-фікс, генерація звіту, перевірка покриття, нормалізація ADR тощо. Замість того щоб кожному скрипту самостійно перелічувати теки в `npm/rules/`, всі вони викликають цю функцію та отримують однаковий, відсортований, відфільтрований список — це гарантує детермінованість порядку обробки правил.
+
+Архітектурно файл підкріплює інваріант «`fix.mjs` обовʼязковий»: будь-яка тека без нього автоматично невидима для всіх споживачів. Це дає змогу тримати у `rules/` допоміжні підтеки (наприклад, шаблони, шаред-файли) без ризику, що вони будуть оброблені як правило.
+
+### Приклад використання
+
+```js
+import { listRuleIds } from './lib/list-rule-ids.mjs'
+import { resolve } from 'node:path'
+
+const bundledRulesDir = resolve(import.meta.dirname, '../../rules')
+
+// 1. Всі правила.
+const all = await listRuleIds(bundledRulesDir)
+// → ['abie', 'changelog', 'feedback', ...]
+
+// 2. Тільки одне правило (з CLI-флагу --rule abie).
+const ruleFlag = process.argv.includes('--rule') ? process.argv[process.argv.indexOf('--rule') + 1] : undefined
+
+const subset = await listRuleIds(bundledRulesDir, ruleFlag)
+// → ['abie']  якщо ruleFlag === 'abie' і таке правило існує
+// → []        якщо ruleFlag не відповідає жодному правилу
+```
+
+### Інтеграція з CLI
+
+Типовий патерн виклику в скриптах проєкту:
+
+1. Скрипт парсить `process.argv` (часто через `mri`/`minimist` або вручну), отримує опційний `--rule <id>`.
+2. Викликає `listRuleIds(rulesDir, ruleFromArgv)` і чекає на результат.
+3. Ітерується по отриманому масиву і виконує цільову дію (fix/check/коверідж) для кожного id.
+
+### Послідовність виконання при виклику
+
+```
+listRuleIds(dir, filter)
+   │
+   ├─ readdir(dir, withFileTypes:true) ── async ──▶ [Dirent...]
+   │
+   ├─ .filter(isDirectory && !startsWith('.'))
+   ├─ .map(e => e.name)
+   ├─ .filter(existsSync(<id>/fix.mjs))      ◀── sync I/O loop
+   ├─ .filter(filter === undefined || id === filter)
+   ├─ .toSorted(localeCompare)
+   │
+   ▼
+Promise<string[]>  (відсортовані id)
+```
+
+### Очікувані помилки
+
+- `ENOENT` / `ENOTDIR` від `readdir` — якщо переданий `bundledRulesDir` неіснуючий або не є директорією. Викликач має або переконатися в коректності шляху перед викликом, або обгорнути виклик у `try/catch`.
+- `EACCES` — якщо немає прав на читання теки.
+
+Усі інші помилки (відсутність окремого `fix.mjs`, відсутність відповідності `filter`) семантично не є помилками — вони лише звужують повернений масив.

package/scripts/lib/docs/load-cursor-config.md

@@ -0,0 +1,147 @@
+# load-cursor-config.mjs
+
+## Огляд
+
+Утилітарний модуль для читання конфігураційного файлу `.n-cursor.json` з кореня репозиторію. Призначений для використання check-скриптами, що обходять файлову систему й мають виключати певні каталоги зі сканування.
+
+Наразі експортує лише одну публічну функцію — `loadCursorIgnorePaths(root)`, яка повертає нормалізовані абсолютні posix-шляхи з масиву `ignore` у конфізі. Якщо конфіг відсутній, пошкоджений, або поле `ignore` має невалідний формат — функція повертає порожній масив без кидання винятків (fail-soft підхід).
+
+Модуль свідомо **не валідує** структуру конфігу повністю — це робота окремої перевірки (наприклад, через `v8r`). Тут перевіряється лише наявність і тип поля `ignore` та його елементів.
+
+Шлях до конфігу зашитий константою `CONFIG_FILE = '.n-cursor.json'` й читається з кореня репозиторію, переданого через параметр `root`.
+
+## Експорти / API
+
+| Експорт                 | Тип                                                | Призначення                                                          |
+| ----------------------- | -------------------------------------------------- | -------------------------------------------------------------------- |
+| `loadCursorIgnorePaths` | `async function (root: string): Promise<string[]>` | Зчитати й нормалізувати список ігнорованих шляхів з `.n-cursor.json` |
+
+Внутрішні (не експортовані) сутності:
+
+| Сутність      | Тип                                          | Призначення                                                        |
+| ------------- | -------------------------------------------- | ------------------------------------------------------------------ |
+| `CONFIG_FILE` | `string` (константа `'.n-cursor.json'`)      | Ім'я конфіг-файлу в корені репозиторію                             |
+| `toAbsPosix`  | `function (root: string, p: string): string` | Нормалізатор шляху до абсолютного posix-формату без trailing-slash |
+
+## Функції
+
+### `toAbsPosix(root, p)`
+
+Внутрішня (приватна для модуля) функція-нормалізатор шляху.
+
+- **Сигнатура:** `function toAbsPosix(root: string, p: string): string`
+- **Параметри:**
+  - `root` — абсолютний корінь репозиторію (використовується для розв'язання відносних шляхів).
+  - `p` — шлях з конфігу; може бути відносним або абсолютним.
+- **Повертає:** абсолютний posix-шлях (роздільник `/`) без жодного завершального `/`.
+- **Алгоритм:**
+  1. Конвертує `p` у рядок через `String(p)` і прибирає пробіли по краях через `trim()`.
+  2. Якщо результат вже абсолютний (`isAbsolute`), використовує його як є; інакше — резолвить відносно `root` через `resolve(root, trimmed)`.
+  3. Замінює нативний роздільник платформи (`sep`) на `/` (через `split(sep).join('/')`) — на Windows це конвертує `\` у `/`.
+  4. У циклі видаляє всі завершальні `/` (нормалізація `foo/bar//` → `foo/bar`).
+- **Side effects:** немає (чиста функція над аргументами).
+
+### `loadCursorIgnorePaths(root)`
+
+Публічна async-функція — точка входу модуля.
+
+- **Сигнатура:** `async function loadCursorIgnorePaths(root: string): Promise<string[]>`
+- **Параметри:**
+  - `root` — абсолютний шлях до кореня репозиторію, де очікується `.n-cursor.json`.
+- **Повертає:** `Promise<string[]>` — масив абсолютних posix-шляхів без trailing-slash; може бути порожнім.
+- **Алгоритм (fail-soft):**
+  1. Обчислює абсолютний шлях до конфіг-файлу через `join(root, CONFIG_FILE)`.
+  2. Якщо файлу немає на диску (`existsSync` повернув `false`) — повертає `[]`.
+  3. Намагається прочитати файл через `readFile(file, 'utf8')` й розпарсити його як JSON. Якщо парсинг кидає виняток (битий JSON, помилка читання тощо) — `catch` повертає `[]`.
+  4. Дістає поле `ignore` з розпарсеного об'єкта через optional chaining (`raw?.ignore`). Якщо поле не є масивом (`Array.isArray` повернув `false`) — повертає `[]`.
+  5. Ітерує по `list`, для кожного елемента:
+     - якщо це не рядок — пропускає;
+     - тримить пробіли; якщо рядок став порожнім — пропускає;
+     - інакше додає в результат `toAbsPosix(root, v)`.
+  6. Повертає накопичений масив `out`.
+- **Side effects:**
+  - Синхронний `existsSync` на дисковий файл `<root>/.n-cursor.json`.
+  - Асинхронне читання того ж файлу через `readFile` (тільки якщо `existsSync` повернув `true`).
+  - Жодних записів, мережевих викликів чи мутацій глобального стану.
+- **Обробка помилок:**
+  - Файл не існує → `[]`.
+  - Файл існує, але JSON битий або `readFile` падає → `[]` (через `try/catch`).
+  - `ignore` не масив, або взагалі відсутнє → `[]`.
+  - Нестрингові або порожні після `trim()` елементи масиву → мовчки пропускаються.
+
+## Залежності
+
+### Node.js built-ins
+
+| Модуль             | Імпортовані сутності                   | Використання                                                                                                             |
+| ------------------ | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `node:fs`          | `existsSync`                           | Синхронна перевірка наявності `.n-cursor.json` перед читанням                                                            |
+| `node:fs/promises` | `readFile`                             | Асинхронне читання вмісту конфіг-файлу як UTF-8                                                                          |
+| `node:path`        | `isAbsolute`, `join`, `resolve`, `sep` | Перевірка абсолютності, склейка шляху до конфігу, розв'язання відносних шляхів, заміна платформного роздільника на posix |
+
+### Зовнішні залежності
+
+Жодних — лише стандартна бібліотека Node.js.
+
+### Конфігураційні артефакти
+
+- `.n-cursor.json` у корені репозиторію — джерело правди для `ignore` (опціональне поле, масив рядків).
+
+## Потік виконання / Використання
+
+### Типовий сценарій виклику
+
+Викликач (наприклад, check-скрипт) передає абсолютний корінь репозиторію й отримує перелік каталогів, які слід виключити з обходу.
+
+```js
+import { loadCursorIgnorePaths } from './load-cursor-config.mjs'
+
+const root = process.cwd() // або інший абсолютний корінь
+const ignored = await loadCursorIgnorePaths(root)
+// ignored: ['/abs/path/.worktrees', '/abs/path/node_modules', ...]
+
+// Далі при обході файлів пропускаємо ті, що під будь-яким із ignored:
+function isIgnored(absPosixPath) {
+  return ignored.some(ig => absPosixPath === ig || absPosixPath.startsWith(ig + '/'))
+}
+```
+
+### Очікуваний формат `.n-cursor.json`
+
+```json
+{
+  "ignore": [".worktrees", "node_modules", "/abs/path/to/skip"]
+}
+```
+
+Інші поля у файлі допустимі — їх ігнорує цей модуль (валідація схеми — окрема відповідальність).
+
+### Послідовність кроків усередині `loadCursorIgnorePaths`
+
+1. `join(root, '.n-cursor.json')` → шлях до конфігу.
+2. `existsSync(file)` → якщо `false`, ранній вихід з `[]`.
+3. `readFile + JSON.parse` у `try/catch` → при будь-якій помилці `[]`.
+4. `Array.isArray(raw?.ignore)` → якщо `false`, `[]`.
+5. Лінійний прохід по `ignore`-елементах: фільтр по типу й непорожності, нормалізація через `toAbsPosix(root, v)`.
+6. Повернення масиву `out`.
+
+### Інваріанти результату
+
+- Усі шляхи — **абсолютні**.
+- Усі шляхи — у **posix-форматі** (роздільник `/`), навіть на Windows.
+- Жоден шлях не має **завершального `/`**.
+- Порядок шляхів — відповідає порядку в `ignore` (вхідні дублікати **не дедуплікуються**).
+- За жодних умов функція не кидає винятки — повертає `[]` як єдиний "поганий" результат.
+
+### Тестування (Rebuild Test)
+
+Перевірка контрактів модуля:
+
+- Файлу немає → `loadCursorIgnorePaths(root)` резолвиться у `[]`.
+- Файл є, але JSON битий → `[]`.
+- Файл є, але `ignore` відсутнє/не масив → `[]`.
+- `ignore` містить нестрингові елементи й порожні рядки — вони відфільтровані; рядкові — нормалізовані до абсолютного posix-шляху без trailing-slash.
+- Відносний шлях у `ignore` (наприклад `"node_modules"`) перетворюється на `<root>/node_modules` у posix-формі.
+- Абсолютний шлях у `ignore` зберігається як є (з можливою конверсією `\` → `/`).
+- На Windows шляхи з `\` конвертуються у `/`.
+- Trailing `/` (один або кілька) видаляються.