@nitra/cursor 3.22.0 → 3.23.0

package/scripts/docs/ensure-nitra-cursor-dev-dependencies.md

@@ -0,0 +1,189 @@
+# ensure-nitra-cursor-dev-dependencies.mjs
+
+## Огляд
+
+Модуль `ensure-nitra-cursor-dev-dependencies.mjs` забезпечує, що пакет `@nitra/cursor` буде оголошений у `devDependencies` workspace-root `package.json` проєкту, в якому виконується CLI `n-cursor`. Якщо запис відсутній і в `devDependencies`, і в `dependencies`, модуль дописує його з діапазоном `^<version>`, узятим з поля `version` з `package.json` фактично завантаженого пакету `@nitra/cursor`.
+
+Призначення: коли користувач викликає `npx @nitra/cursor` (зокрема команду `check`), node-кеш npx містить пакет, але після наступного `bun install` / `npm install` цей кеш може не відтворити пакет у проєкті. Дописавши пакет у `devDependencies` workspace-root, модуль гарантує, що `n-cursor` і його допоміжні скрипти з `node_modules/@nitra/cursor/scripts/` стануть відтвореною частиною проєкту й не залежатимуть від кешу npx.
+
+Workspace-root визначається мінімалістично: береться `package.json` поруч зі стартовою директорією (зазвичай `process.cwd()`) і вважається workspace-root, якщо в ньому є поле `workspaces`. Підйом по дереву директорій не виконується.
+
+Модуль написаний як ESM (`.mjs`), використовує лише стандартну бібліотеку Node.js, не має сторонніх залежностей і виконує синхронні файлові операції лише для перевірки існування (`existsSync`). Решта IO — асинхронна через `node:fs/promises`.
+
+## Експорти / API
+
+Модуль експортує дві асинхронні функції:
+
+- `readBundledPackageVersion()` — повертає версію встановленого пакету `@nitra/cursor` або `null`.
+- `ensureNitraCursorInRootDevDependencies(root, options?)` — головна точка входу: перевіряє стан проєкту й, за потреби, мутує його `package.json`. Повертає булеве значення про факт запису на диск.
+
+Внутрішні (не експортовані) функції модуля:
+
+- `readJsonObject(path)` — м’який парсер JSON-обʼєкта з диска.
+- `readAdjacentWorkspaceRootPackageJson(startDir)` — читання `package.json` поряд зі стартовою директорією за умови, що це workspace-root.
+
+Константа модульного рівня:
+
+- `PACKAGE_NAME` (`'@nitra/cursor'`) — імʼя пакету, який забезпечується у `devDependencies`.
+
+Внутрішній стан модуля (обчислюється один раз під час імпорту):
+
+- `scriptDir` — абсолютна директорія, в якій лежить сам файл (отримана з `import.meta.url`).
+- `bundledPkgPath` — обчислений шлях до `package.json` пакету `@nitra/cursor`: на один рівень вище `scriptDir`, бо файл лежить у каталозі `scripts/` всередині пакету.
+
+## Функції
+
+### `readBundledPackageVersion()`
+
+Сигнатура: `readBundledPackageVersion(): Promise<string | null>` (експортується).
+
+Параметри: відсутні.
+
+Поведінка:
+
+1. Перевіряє існування файлу `bundledPkgPath` через `existsSync`. Якщо файлу немає — повертає `null` без подальшої роботи.
+2. Читає вміст файлу як UTF-8 через `readFile`.
+3. Парсить вміст як JSON.
+4. Якщо поле `version` у розпарсеному обʼєкті є рядком — повертає його; інакше — повертає `null`.
+5. Будь-яка помилка читання чи парсингу глушиться `try/catch` і дає `null`.
+
+Повертає: `Promise<string | null>` — текстова версія (наприклад, `'1.11.14'`) або `null` за відсутності файлу / некоректного JSON / нерядкового `version`.
+
+Side effects: лише read-IO (один read від диска). Нічого не пише й не логує.
+
+### `readJsonObject(path)`
+
+Сигнатура: `readJsonObject(path: string): Promise<Record<string, unknown> | null>` (внутрішня).
+
+Параметри:
+
+- `path` — абсолютний шлях до JSON-файлу.
+
+Поведінка:
+
+1. Намагається прочитати файл як UTF-8. Помилка читання повертає `null`.
+2. Намагається розпарсити вміст як JSON. Помилка парсингу повертає `null`.
+3. Перевіряє, що розпарсене значення — це не `null`, типу `object`, і не масив. Якщо умова не виконана — повертає `null`. Інакше повертає сам обʼєкт.
+
+Повертає: `Promise<Record<string, unknown> | null>` — JSON-обʼєкт або `null`.
+
+Side effects: read-IO.
+
+### `readAdjacentWorkspaceRootPackageJson(startDir)`
+
+Сигнатура: `readAdjacentWorkspaceRootPackageJson(startDir: string): Promise<{ path: string, pkg: Record<string, unknown> } | null>` (внутрішня).
+
+Параметри:
+
+- `startDir` — директорія, від якої починається пошук (зазвичай `process.cwd()` процесу CLI).
+
+Поведінка:
+
+1. Будує `pkgPath = join(startDir, 'package.json')`.
+2. Через `existsSync` перевіряє наявність файлу. Якщо файлу немає — повертає `null`.
+3. Викликає `readJsonObject(pkgPath)`. Якщо результат — не обʼєкт, повертає `null`.
+4. Через `Object.hasOwn(pkg, 'workspaces')` перевіряє наявність поля `workspaces` (саме власне поле, а не з прототипа). Якщо поле є — повертає `{ path, pkg }`; інакше — `null`.
+
+Повертає: `Promise<{ path, pkg } | null>` — пара «шлях/обʼєкт» для workspace-root або `null` для не-workspace-root.
+
+Side effects: read-IO. Жодних мутацій диска / логів.
+
+### `ensureNitraCursorInRootDevDependencies(root, options?)`
+
+Сигнатура: `ensureNitraCursorInRootDevDependencies(root: string, options?: { bundledVersion?: string | null, silent?: boolean }): Promise<boolean>` (експортується).
+
+Параметри:
+
+- `root` — стартова директорія проєкту, зазвичай `process.cwd()` процесу CLI `n-cursor`.
+- `options` — необовʼязковий обʼєкт:
+  - `bundledVersion` — попередньо задана версія для тестів; якщо передано — використовується замість виклику `readBundledPackageVersion()`. `null` тут інтерпретується як «викликати fallback» через оператор `??`.
+  - `silent` — якщо `true`, не друкувати повідомлення про оновлення у `stdout`.
+
+Алгоритм:
+
+1. Викликає `readAdjacentWorkspaceRootPackageJson(root)`. Якщо результат `null` (немає workspace-root) — повертає `false`.
+2. Деструктурує `{ path: pkgPath, pkg }`.
+3. Якщо в `pkg.devDependencies` (за умови, що це обʼєкт) присутній ключ `PACKAGE_NAME` — повертає `false` (вже є).
+4. Якщо в `pkg.dependencies` (за умови, що це обʼєкт) присутній ключ `PACKAGE_NAME` — повертає `false` (вже є в runtime deps; додавати дубль до dev не потрібно).
+5. Визначає версію: `options.bundledVersion ?? await readBundledPackageVersion()`. Якщо результат фолсі (`null`, порожній рядок) — повертає `false`.
+6. Гарантує, що `pkg.devDependencies` — це валідний обʼєкт. Якщо там відсутнє поле, `null`, не-обʼєкт або масив — перезаписує його на `{}`.
+7. Записує `pkg.devDependencies[PACKAGE_NAME] = ` `^<ver>`.
+8. Серіалізує `pkg` з відступом 2 пробіли через `JSON.stringify(pkg, null, 2)`, додає завершальний перевід рядка `\n`, пише через `writeFile` у `pkgPath` у UTF-8.
+9. Якщо `options.silent` не встановлено — друкує `📝 Додано <PACKAGE_NAME>@^<ver> у devDependencies у package.json\n` у `stdout` через `console.log`.
+10. Повертає `true`.
+
+Повертає: `Promise<boolean>` — `true`, якщо `package.json` дійсно змінено на диску; `false` у всіх no-op-ситуаціях (немає workspace-root, пакет вже задекларовано, версія недоступна).
+
+Side effects:
+
+- Читання `package.json` workspace-root.
+- Можливий запис `package.json` workspace-root (мутація вмісту).
+- Можливий запис у `stdout` через `console.log` (можна заглушити через `options.silent`).
+
+Особливості:
+
+- Перевірка «вже є в deps» поблажлива: якщо `devDependencies` / `dependencies` присутнє, але не є обʼєктом (некоректний `package.json`), модуль трактує це як «нема» і йде далі.
+- Перезапис `pkg.devDependencies` на `{}` у випадку, коли поле не є обʼєктом, спрямований на корекцію некоректного стану `package.json`. Це означає, що нечитабельне поле буде втрачено.
+- Серіалізація використовує `JSON.stringify` із відступом 2 і завершальним `\n`. Будь-яке стилістичне форматування з оригіналу (наприклад, табуляції чи tab-width=4) буде нормалізоване до 2 пробілів.
+
+## Залежності
+
+Зовнішніх npm-залежностей немає. Використовуються лише вбудовані модулі Node.js:
+
+- `node:fs`
+  - `existsSync` — синхронна перевірка існування файлу.
+- `node:fs/promises`
+  - `readFile` — асинхронне читання файлу як UTF-8.
+  - `writeFile` — асинхронний запис файлу як UTF-8.
+- `node:path`
+  - `dirname` — отримати директорію з шляху.
+  - `join` — побудувати шлях.
+- `node:url`
+  - `fileURLToPath` — конвертувати `file://`-URL у файловий шлях.
+
+Зовнішні споживачі модуля:
+
+- CLI `@nitra/cursor` (`bin`), що викликає `ensureNitraCursorInRootDevDependencies(process.cwd())` під час кожного запуску (зокрема перед `check`), щоб довести стан `package.json` проєкту до бажаного.
+- Тестовий код може передавати `bundledVersion` у `options`, щоб не залежати від реальної версії з диска.
+
+## Потік виконання / Використання
+
+Типовий потік під час `npx @nitra/cursor check` у workspace-root:
+
+1. CLI імпортує модуль і викликає `await ensureNitraCursorInRootDevDependencies(process.cwd())`.
+2. Модуль читає `<cwd>/package.json`. Якщо там немає поля `workspaces` — це не workspace-root, повертається `false`, файл не змінюється.
+3. Якщо `package.json` має `workspaces` і вже містить `@nitra/cursor` у `devDependencies` або `dependencies` — повертається `false`, файл не змінюється.
+4. Інакше модуль читає `version` з `package.json` встановленого пакету `@nitra/cursor` (на рівень вище за `scripts/`), формує діапазон `^<version>` і записує його в `pkg.devDependencies['@nitra/cursor']`.
+5. Серіалізований JSON записується назад у `<cwd>/package.json`.
+6. У `stdout` логується повідомлення про додавання (якщо не задано `silent: true`).
+7. Повертається `true`.
+
+Приклад використання:
+
+```js
+import { ensureNitraCursorInRootDevDependencies } from '@nitra/cursor/scripts/ensure-nitra-cursor-dev-dependencies.mjs'
+
+const changed = await ensureNitraCursorInRootDevDependencies(process.cwd())
+if (changed) {
+  // package.json було оновлено — можна підказати користувачу зробити bun install
+}
+```
+
+Приклад використання з тестового сетапу:
+
+```js
+import { ensureNitraCursorInRootDevDependencies } from '../scripts/ensure-nitra-cursor-dev-dependencies.mjs'
+
+await ensureNitraCursorInRootDevDependencies(tmpDir, {
+  bundledVersion: '9.9.9',
+  silent: true
+})
+```
+
+Передумови, на які покладається модуль:
+
+- Файл `ensure-nitra-cursor-dev-dependencies.mjs` лежить у `<package>/scripts/`, а `package.json` пакету `@nitra/cursor` — у `<package>/package.json`. Якщо структуру переміщено, шлях `bundledPkgPath` стане некоректним.
+- Робоче дерево, передане як `root`, має містити `package.json` із полем `workspaces`. Якщо CLI стартовано всередині workspace-пакету (а не в корені) — модуль нічого не зробить (`false`).
+- Поле `version` у `package.json` пакету `@nitra/cursor` має бути рядком; інакше додавання не відбудеться.
+
+Інваріант: повторні виклики модуля у тому самому проєкті стають no-op (другий виклик бачить `@nitra/cursor` у `devDependencies` і повертає `false`).

package/scripts/lib/changed-files.mjs

@@ -15,7 +15,10 @@ import { spawnSync } from 'node:child_process'
 function gitLines(args, cwd) {
   const r = spawnSync('git', args, { cwd, encoding: 'utf8' })
   if (r.status !== 0 || r.error) return []
-  return r.stdout.split('\n').map(s => s.trim()).filter(Boolean)
+  return r.stdout
+    .split('\n')
+    .map(s => s.trim())
+    .filter(Boolean)
 }
 
 /**

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

@@ -0,0 +1,149 @@
+# changed-files.mjs
+
+## Огляд
+
+Модуль `changed-files.mjs` — допоміжна бібліотека для збору переліку змінених файлів у робочому дереві git-репозиторію. Використовується lint-оркестратором у quick-режимі та `coverage --changed` для визначення scope-у файлів, на яких потрібно прогнати перевірки.
+
+Логіка модуля:
+
+- збирає tracked-modified та staged файли через `git diff` (з `--diff-filter=ACMR`, тобто Added/Copied/Modified/Renamed — без Deleted);
+- додає untracked файли через `git ls-files --others --exclude-standard` (з повагою до `.gitignore`);
+- дедуплікує об'єднаний список через `Set`;
+- повертає relative-posix шляхи відносно `cwd`;
+- поза git-репо або при помилці git мовчки повертає порожній список (для `gitLines`);
+- для режиму "since base" — fail-closed: якщо базовий комміт недосяжний, кидає явну помилку, щоб gate не пройшов мовчки.
+
+Видалені файли свідомо не включаються — лінтити неіснуючий файл немає сенсу.
+
+## Експорти / API
+
+Модуль експортує дві функції:
+
+| Експорт                    | Тип                                                | Призначення                                                                                                                  |
+| -------------------------- | -------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| `collectChangedFiles`      | `(cwd?: string) => string[]`                       | Список змінених + untracked файлів робочого дерева відносно `HEAD`.                                                          |
+| `collectChangedFilesSince` | `(base: string \| null, cwd?: string) => string[]` | Список змінених + untracked файлів **відносно довільного базового комміту**. Без `base` — fallback на `collectChangedFiles`. |
+
+Внутрішня (неекспортована) функція:
+
+| Внутрішнє  | Тип                                         | Призначення                                                                                    |
+| ---------- | ------------------------------------------- | ---------------------------------------------------------------------------------------------- |
+| `gitLines` | `(args: string[], cwd: string) => string[]` | Виконує `git <args>` у `cwd` і повертає непорожні trim-нуті рядки stdout або `[]` при помилці. |
+
+## Функції
+
+### `gitLines(args, cwd)` (internal)
+
+Виклик git-команди з парсингом stdout у масив рядків.
+
+- **Сигнатура:** `function gitLines(args: string[], cwd: string): string[]`
+- **Параметри:**
+  - `args` — масив аргументів для `git` (наприклад `['diff', 'HEAD', '--name-only']`).
+  - `cwd` — робоча директорія для процесу `git`.
+- **Повертає:** масив непорожніх рядків stdout (після `trim`). Якщо `r.status !== 0` або є `r.error` — повертає `[]`.
+- **Side effects:**
+  - Синхронно спавнить процес `git` через `spawnSync` з `node:child_process`;
+  - не пише в stdout/stderr батьківського процесу (всі потоки збираються через `encoding: 'utf8'`);
+  - не кидає винятків — fail-silent.
+
+### `collectChangedFiles(cwd?)`
+
+Збирає список змінених + untracked файлів робочого дерева відносно `HEAD`.
+
+- **Сигнатура:** `function collectChangedFiles(cwd?: string): string[]`
+- **Параметри:**
+  - `cwd` (опційно, дефолт `process.cwd()`) — корінь git-репо.
+- **Алгоритм:**
+  1. `git diff HEAD --name-only --diff-filter=ACMR` — повертає всі tracked файли, які відрізняються від `HEAD` (staged + unstaged), фільтр `ACMR` відсікає Deleted.
+  2. `git ls-files --others --exclude-standard` — повертає untracked файли, які не ігноруються `.gitignore`.
+  3. Об'єднання обох списків через `new Set([...modified, ...untracked])` для дедуплікації.
+- **Повертає:** `string[]` — унікальні relative-posix шляхи без видалених файлів.
+- **Поведінка поза git-репо / при помилці:** `gitLines` мовчки повертає `[]` для обох викликів, тож результат — порожній масив.
+
+### `collectChangedFilesSince(base, cwd?)`
+
+Збирає список змінених + untracked файлів відносно довільного базового комміту. Призначено для сценаріїв, де базовий комміт зафіксовано у стані flow-турнікета (executor комітить кожен крок, тож потрібно ловити зміни «від base», а не «від HEAD»).
+
+- **Сигнатура:** `function collectChangedFilesSince(base: string | null, cwd?: string): string[]`
+- **Параметри:**
+  - `base` — SHA/ref базового комміту (типово `metadata.base_commit` зі стану flow). Якщо `null`/`undefined`/порожній — fallback на `collectChangedFiles(cwd)`.
+  - `cwd` (опційно, дефолт `process.cwd()`) — корінь git-репо.
+- **Алгоритм:**
+  1. Якщо `base` falsy — повертає результат `collectChangedFiles(cwd)`.
+  2. Перевіряє досяжність base через `git rev-parse --verify --quiet <base>^{commit}`.
+  3. Якщо verify не успішний (`status !== 0` або `error`) — **кидає `Error`** з повідомленням: `collectChangedFilesSince: base-комміт «<base>» недосяжний у <cwd> (rebase/force-update?) — coverage --changed не може визначити scope`.
+  4. `git diff <base> --name-only --diff-filter=ACMR` — **без** `..`/`...`, **без** `HEAD`. Така форма порівнює base-комміт із поточним **робочим деревом**, тобто ловить одночасно: закомічене від base, staged та незакомічені модифікації.
+  5. `git ls-files --others --exclude-standard` — untracked файли (як у `collectChangedFiles`).
+  6. Дедуплікація через `Set`.
+- **Повертає:** `string[]` — унікальні relative-posix шляхи без видалених файлів.
+- **Контракт fail-closed:** на відміну від `collectChangedFiles`, ця функція **навмисно** не маскує помилку недосяжного base. Інакше `git diff` повернув би exit 128, `gitLines` дав би `[]`, і gate мовчки пройшов би без перевірки — це порушує безпеку coverage-перевірки.
+- **Side effects:**
+  - спавнить два-три git-процеси (один verify + два data-збори, або один fallback);
+  - може кинути `Error` (єдина точка throw у модулі).
+
+## Залежності
+
+### Зовнішні (built-in Node.js)
+
+- `node:child_process` — імпорт `spawnSync` для синхронного виклику git-команд із захопленням stdout.
+
+### Системні (runtime)
+
+- `git` — має бути доступний у `PATH` процесу. За відсутності `gitLines` поверне `[]` (через `r.error`/ненульовий статус).
+
+### Внутрішні модулі
+
+Файл не імпортує жодного локального модуля проєкту (zero-dependency бібліотечний листок).
+
+## Потік виконання / Використання
+
+### Quick-lint (lint-оркестратор)
+
+```js
+import { collectChangedFiles } from './changed-files.mjs'
+
+const files = collectChangedFiles()
+// → лінт тільки цих файлів, замість обходу всього монорепо
+```
+
+Quick-режим прагне мінімізувати IO: лінтить лише те, що користувач щойно змінив у дереві (modified + staged + untracked), ігноруючи решту репо.
+
+### Coverage / flow-турнікет
+
+```js
+import { collectChangedFilesSince } from './changed-files.mjs'
+
+const base = metadata.base_commit // SHA, зафіксований при старті flow-кроку
+const scope = collectChangedFilesSince(base, repoRoot)
+// → файли, які змінилися з моменту base, незалежно від того,
+//   чи їх вже закомічено в проміжних кроках executor-а
+```
+
+Чому саме `git diff <base>` без `..`/`...`:
+
+- `git diff A..B` — порівнює дерева A та B, **ігнорує** робоче дерево;
+- `git diff A...B` — порівнює B з merge-base(A,B), теж ігнорує робоче дерево;
+- `git diff <base>` (один аргумент) — порівнює `<base>` із **робочим деревом** (включно з unstaged змінами).
+
+Це критично для flow-турнікета, де executor може як комітити проміжні зміни, так і залишати їх unstaged — gate повинен побачити всі зміни від `base` однаково.
+
+### Поведінка при недосяжному base
+
+Якщо у репозиторії стався rebase, force-push або shallow clone обрізав історію — `<base>` може стати недосяжним. У такому разі:
+
+- `collectChangedFiles` (без base) — поведінка незмінна, працює від `HEAD`;
+- `collectChangedFilesSince(base, cwd)` — **кидає Error** до того, як викликати `git diff`, щоб coverage-gate явно впав, а не пройшов на порожньому scope.
+
+### Формат шляхів
+
+Усі повернені шляхи — POSIX-style relative до `cwd` (як їх віддає git за замовчуванням). На Windows git також віддає forward slashes, тож додаткової нормалізації немає.
+
+### Точки помилок (summary)
+
+| Сценарій                                      | Поведінка                                                                                                                          |
+| --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| Поза git-репо                                 | `collectChangedFiles` → `[]`; `collectChangedFilesSince(null)` → `[]`; `collectChangedFilesSince('SHA')` → `Error` (verify впаде). |
+| `git` відсутній у PATH                        | Усі виклики `gitLines` → `[]`; `collectChangedFilesSince` із `base` → `Error` (verify впаде).                                      |
+| `base` досяжний                               | `collectChangedFilesSince` повертає список (можливо порожній).                                                                     |
+| `base` недосяжний (rebase/force-push/shallow) | `collectChangedFilesSince` кидає `Error`.                                                                                          |
+| `base` falsy (`null`/`undefined`/`''`/`0`)    | `collectChangedFilesSince` → результат `collectChangedFiles(cwd)`.                                                                 |

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`, що насправді є файлом, а не каталогом → пропускається без помилки.