@nitra/cursor 12.8.3 → 12.8.4

package/rules/npm-module/js/skill_meta.mjs

@@ -15,15 +15,15 @@ import { parseSkillAutoSpec, readSkillMetaRaw } from '../../../scripts/lib/skill
 function checkSkillFields(id, raw, reporter) {
   let ok = true
   if (typeof raw.worktree !== 'boolean') {
-    reporter.fail(`skills/${id}: meta.json.worktree має бути boolean`)
+    reporter.fail(`skills/${id}: main.json.worktree має бути boolean`)
     ok = false
   }
   if (raw.auto !== undefined && parseSkillAutoSpec(raw.auto) === null) {
-    reporter.fail(`skills/${id}: meta.json.auto нерозпізнане — очікується "завжди" або непорожній масив правил`)
+    reporter.fail(`skills/${id}: main.json.auto нерозпізнане — очікується "завжди" або непорожній масив правил`)
     ok = false
   }
   if (raw.requireRoot !== undefined && typeof raw.requireRoot !== 'boolean') {
-    reporter.fail(`skills/${id}: meta.json.requireRoot має бути boolean`)
+    reporter.fail(`skills/${id}: main.json.requireRoot має бути boolean`)
     ok = false
   }
   if (raw.worktree === true && raw.requireRoot === false) {
@@ -46,20 +46,20 @@ function checkSkill(id, skillDir, reporter) {
   let skillOk = true
 
   if (existsSync(join(skillDir, 'auto.md'))) {
-    reporter.fail(`skills/${id}: залишковий auto.md — видали (метадані тепер у meta.json)`)
+    reporter.fail(`skills/${id}: залишковий auto.md — видали (метадані тепер у main.json)`)
     skillOk = false
   }
 
   const raw = readSkillMetaRaw(skillDir)
   if (!raw) {
-    reporter.fail(`skills/${id}: відсутній або невалідний meta.json (очікується {"auto"?, "worktree": bool})`)
+    reporter.fail(`skills/${id}: відсутній або невалідний main.json (очікується {"auto"?, "worktree": bool})`)
     return
   }
 
   if (!checkSkillFields(id, raw, reporter)) skillOk = false
 
   if (skillOk) {
-    reporter.pass(`skills/${id}: meta.json валідний`)
+    reporter.pass(`skills/${id}: main.json валідний`)
   }
 }
 

package/rules/test/js/docs/index.md

@@ -6,11 +6,11 @@ resource: npm/rules/test/js/
 
 # npm/rules/test/js
 
-| Файл                                                        | Тип       |
-| ----------------------------------------------------------- | --------- |
-| [cargo_mutants_config.mjs](cargo_mutants_config.md)         | JS Module |
-| [location.mjs](location.md)                                 | JS Module |
-| [no-process-chdir.mjs](no-process-chdir.md)                 | JS Module |
-| [no-relative-fs-path.mjs](no-relative-fs-path.md)           | JS Module |
-| [stryker_config.mjs](stryker_config.md)                     | JS Module |
+| Файл | Тип |
+|---|---|
+| [cargo_mutants_config.mjs](cargo_mutants_config.md) | JS Module |
+| [location.mjs](location.md) | JS Module |
+| [no-process-chdir.mjs](no-process-chdir.md) | JS Module |
+| [no-relative-fs-path.mjs](no-relative-fs-path.md) | JS Module |
+| [stryker_config.mjs](stryker_config.md) | JS Module |
 | [vitest-config-pool-forks.mjs](vitest-config-pool-forks.md) | JS Module |

package/rules/test/js/docs/stryker_config.md

@@ -3,48 +3,31 @@ type: JS Module
 title: stryker_config.mjs
 resource: npm/rules/test/js/stryker_config.mjs
 docgen:
-  crc: 7ea109c6
-  score: 95
+  crc: be62c446
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
 ---
 
-Цей файл виконує перевірку наявності певних файлів та конфігурацій у кореневих пакетах. Код працює з конфігами, визначеними у `mutation.json` та `package.json`, для забезпечення певних станів у системі.
+## Огляд
+
+Модуль ініціалізує та налаштовує середовище для покриття коду, перевіряючи конфігурації, зокрема `mutation.json` та `package.json`. Він створює або оновлює конфігураційні файли Stryker, Vue-макросів та Vitest для кожного знайденого кореневого каталогу JavaScript. Функція `check` виконує перевірку, ігноруючи каталоги `node_modules`. Поведінка модуля фіксується за маркером (test.mdc). Модуль перехоплює помилки (fail-safe) і не кидає винятків назовні.
 
 ## Поведінка
 
-1. Перевірити наявність `js` у конфігурації.
-2. Зібрати кореневі пакети.
-3. Перевірити наявність базових конфігурацій.
-4. Перевірити наявність базлайн-файлів.
-5. Для кожного кореневого пакета перевірити наявність `.vue` файлів.
-6. Для кожного кореневого пакета згенерувати ім'я конфігурації.
-7. Для кожного кореневого пакета перевірити наявність необхідних базлайн-файлів.
-8. Для кожного кореневого пакета перевірити наявність `stryker.config.mjs`.
-9. Для кожного кореневого пакета перевірити наявність `vitest.config.mjs` або `vitest.config.js`.
-10. Для кожного кореневого пакета перевірити наявність базових базлайн-файлів.
-11. Для кожного кореневого пакета перевірити наявність `stryker.config.mjs`.
-12. Для кожного кореневого пакета перевірити наявність `vitest.config.mjs` або `vitest.config.js`.
-13. Для кожного кореневого пакета перевірити наявність базових базлайн-файлів.
-14. Для кожного кореневого пакета перевірити наявність `stryker.config.mjs`.
-15. Для кожного кореневого пакета перевірити наявність `vitest.config.mjs` або `vitest.config.js`.
-16. Для кожного кореневого пакета перевірити наявність базових базлайн-файлів.
-17. Для кожного кореневого пакета перевірити наявність `stryker.config.mjs`.
-18. Для кожного кореневого пакета перевірити наявність `vitest.config.mjs` або `vitest.config.js`.
-19. Для кожного кореневого пакета перевірити наявність базових базлайн-файлів.
-20. Для кожного кореневого пакета перевірити наявність `stryker.config.mjs`.
-21. Для кожного кореневого пакета перевірити наявність `vitest.config.mjs` або `vitest.config.js`.
-22. Для кожного кореневого пакета перевірити наявність базових базлайн-файлів.
-23. Для кожного кореневого пакета перевірити наявність `stryker.config.mjs`.
-24. Для кожного кореневого пакета перевірити наявність `vitest.config.mjs` або `vitest.config.js`.
-25. Для кожного кореневого пакета перевірити наявність базових базлайн-файлів.
-26. Для кожного кореневого пакета перевірити наявність `stryker.config.mjs`.
-27. Для кожного кореневого пакета перевірити наявність `vitest.config.mjs` або `vitest.config.js`.
-28. Для кожного кореневого пакета перевірити наявність базових базлайн-файлів.
-29. Для кожного кореневого пакета перевірити наявність `stryker.config.mjs`.
-30. Для кожного кореневого пакета перевірити наявність `vitest.config.mjs` або `vitest.config.js`.
+1. Викликається `check` для ініціалізації процесу перевірки.
+2. Перевіряється, чи у конфігурації дозволено перевірку JavaScript. Якщо ні, процес завершується успішно.
+3. Знаходяться всі кореневі каталоги JavaScript у робочому просторі. Якщо їх немає, процес завершується з помилкою.
+4. Перевіряється наявність усіх канонічних базових конфігураційних файлів. Якщо хоча б один відсутній, процес завершується з помилкою.
+5. Для кожного знайденого кореневого каталогу JavaScript:
+    а. Визначається, чи містить цей каталог файли Vue.
+    б. Створюється або оновлюється конфігураційний файл Stryker для цього каталогу. Якщо файл відсутній, він копіюється з канонічного базового файлу, замінюючи ім'я конфігурації Vitest на фактичне ім'я конфігу каталогу. Якщо файл існує, він залишається без змін.
+    в. Якщо каталог містить файли Vue і конфігураційний файл Stryker вже існував, виконується аугментація конфігурації. Це додає локальний плагін Vue-макросів до конфігурації Stryker, якщо він відсутній.
+    г. Створюється або оновлюється конфігураційний файл плагіна Vue-макросів.
+    д. Створюється або оновлюється конфігураційний файл Vitest для каталогу, використовуючи фактичне ім'я конфігу.
+6. Виконується гарантія, що файли з результатами тестів Stryker та покриття (lcov) не потрапляють у систему контролю версій. Якщо додаються нові патерни до `.gitignore`, це фіксується як успіх (test.mdc).
+7. Процес завершується з кодом виходу, що відображає успіх або помилку.
 
 ## Гарантії поведінки
 
 - Перехоплює помилки і не пропускає винятків назовні (fail-safe).
-- За невдачі повертає значення помилки (`false`/`null`/`Err`) замість генерування винятку чи паніки.
 - Свідомо пропускає шляхи: `node_modules`.
-- Не звертається до мережі.

package/rules/test/js/docs/vitest-config-pool-forks.md

@@ -3,27 +3,29 @@ type: JS Module
 title: vitest-config-pool-forks.mjs
 resource: npm/rules/test/js/vitest-config-pool-forks.mjs
 docgen:
-  crc: bb04a54b
+  crc: c8640fd7
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 100
 ---
 
-Огляд
-Файл виконує перевірку конфігураційного файлу для підтвердження наявності певного параметра. Це робиться для запобігання гонці у process.cwd між паралельними тестовими файлами (test.mdc).
+## Огляд
+
+Модуль визначає, чи встановлено режим `pool: 'forks'` у конфігураційному файлі Vitest. Перевірка здійснюється у `vitest.config.mjs` або `vitest.config.js` кореневого репозиторію. Це забезпечує коректну поведінку при паралельному запуску тестових файлів. Результат перевірки фіксується у test.mdc.
 
 ## Поведінка
 
-1. Знайти файл конфігурації з назвою vitest.config.mjs або vitest.config.js у вказаному шляху.
-2. Якщо файл знайдено, прочитати його вміст.
-3. Перевірити вміст файлу на наявність патерну pool: 'forks'.
-4. Якщо патерн знайдено, повідомити про успішне виконання перевірки.
-5. Якщо патерн відсутній, повідомити про невдачу, вказуючи, що конфігурація повинна містити pool: 'forks' для захисту від гонки у process.cwd між паралельними test files (test.mdc).
-6. Якщо файл конфігурації не знайдено, повідомити, що перевірка пропущено.
+1. Визначається назва конфігураційного файлу Vitest, шукаючи спочатку `vitest.config.mjs`, а потім `vitest.config.js` у корені репозиторію.
+2. Якщо конфігураційний файл відсутній, виконується пропуск перевірки, і повертається код успіху.
+3. Якщо конфігураційний файл знайдено, його вміст зчитується.
+4. Перевіряється, чи містить вміст конфігураційного файлу рядок, що вказує на використання `pool: 'forks'`.
+5. Якщо рядок знайдено, фіксується успіх (test.mdc).
+6. Якщо рядок не знайдено, фіксується помилка (test.mdc), оскільки це необхідно для захисту від гонки у `process.cwd` між паралельними тестовими файлами.
+7. Функція `check` повертає код виходу, що відображає результат перевірки (0 для успіху/пропуску, 1 для помилки).
 
 ## Публічний API
 
-check — перевіряє, чи налаштування `vitest.config.{mjs,js}` використовує `pool: 'forks'`. (test.mdc)
+check — перевіряє наявність конфігурації `pool: 'forks'` у файлі `vitest.config.{mjs,js}`. (test.mdc)
 
 ## Гарантії поведінки
 
-- Read-only: файл не виконує операцій запису у файлову систему.
-- Не звертається до мережі.
+- Read-only: не виконує операцій запису (ФС/БД).

package/schemas/v8r-catalog.json

@@ -28,14 +28,14 @@
     },
     {
       "name": "n-cursor skill meta",
-      "description": "Маніфест skill-пакета n-cursor (npm/skills/<id>/meta.json) — назва, тригери, дозволи",
-      "fileMatch": ["npm/skills/*/meta.json"],
+      "description": "Маніфест skill-пакета n-cursor (npm/skills/<id>/main.json) — назва, тригери, дозволи",
+      "fileMatch": ["npm/skills/*/main.json"],
       "url": "https://unpkg.com/@nitra/cursor/schemas/skill-meta.json"
     },
     {
       "name": "n-cursor rule meta",
-      "description": "Маніфест rule-пакета n-cursor (npm/rules/<id>/meta.json) — назва, опис, версія правила",
-      "fileMatch": ["npm/rules/*/meta.json"],
+      "description": "Маніфест rule-пакета n-cursor (npm/rules/<id>/main.json) — назва, опис, версія правила",
+      "fileMatch": ["npm/rules/*/main.json"],
       "url": "https://unpkg.com/@nitra/cursor/schemas/rule-meta.json"
     }
   ]

package/scripts/docs/index.md

@@ -6,20 +6,20 @@ resource: npm/scripts/
 
 # npm/scripts
 
-| Файл                                                                                | Тип       |
-| ----------------------------------------------------------------------------------- | --------- |
-| [auto-rules.mjs](auto-rules.md)                                                     | JS Module |
-| [auto-skills.mjs](auto-skills.md)                                                   | JS Module |
-| [build-agents-commands.mjs](build-agents-commands.md)                               | JS Module |
-| [cli-entry.mjs](cli-entry.md)                                                       | JS Module |
-| [coverage-fix-extract.mjs](coverage-fix-extract.md)                                 | JS Module |
-| [coverage-fix.mjs](coverage-fix.md)                                                 | JS Module |
+| Файл | Тип |
+|---|---|
+| [auto-rules.mjs](auto-rules.md) | JS Module |
+| [auto-skills.mjs](auto-skills.md) | JS Module |
+| [build-agents-commands.mjs](build-agents-commands.md) | JS Module |
+| [cli-entry.mjs](cli-entry.md) | JS Module |
+| [coverage-fix-extract.mjs](coverage-fix-extract.md) | JS Module |
+| [coverage-fix.mjs](coverage-fix.md) | JS Module |
 | [ensure-nitra-cursor-dev-dependencies.mjs](ensure-nitra-cursor-dev-dependencies.md) | JS Module |
-| [post-tool-use-check.mjs](post-tool-use-check.md)                                   | JS Module |
-| [post-tool-use-fix.mjs](post-tool-use-fix.md)                                       | JS Module |
-| [rename-yaml-extensions.mjs](rename-yaml-extensions.md)                             | JS Module |
-| [skills-cli.mjs](skills-cli.md)                                                     | JS Module |
-| [sync-claude-config.mjs](sync-claude-config.md)                                     | JS Module |
-| [sync-setup-bun-deps-action.mjs](sync-setup-bun-deps-action.md)                     | JS Module |
-| [upgrade-nitra-cursor-and-install.mjs](upgrade-nitra-cursor-and-install.md)         | JS Module |
-| [worktree-cli.mjs](worktree-cli.md)                                                 | JS Module |
+| [post-tool-use-check.mjs](post-tool-use-check.md) | JS Module |
+| [post-tool-use-fix.mjs](post-tool-use-fix.md) | JS Module |
+| [rename-yaml-extensions.mjs](rename-yaml-extensions.md) | JS Module |
+| [skills-cli.mjs](skills-cli.md) | JS Module |
+| [sync-claude-config.mjs](sync-claude-config.md) | JS Module |
+| [sync-setup-bun-deps-action.mjs](sync-setup-bun-deps-action.md) | JS Module |
+| [upgrade-nitra-cursor-and-install.mjs](upgrade-nitra-cursor-and-install.md) | JS Module |
+| [worktree-cli.mjs](worktree-cli.md) | JS Module |

package/scripts/docs/sync-setup-bun-deps-action.md

@@ -3,28 +3,27 @@ type: JS Module
 title: sync-setup-bun-deps-action.mjs
 resource: npm/scripts/sync-setup-bun-deps-action.mjs
 docgen:
-  crc: 098d7209
+  crc: 327991b2
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
 ---
 
-Файл містить конфігурацію GitHub Action `setup-bun-deps`, яка автоматично встановлює залежності проєкту Bun. Він використовується workflow для підготовки середовища проєкту, забезпечуючи узгодженість та спрощуючи виконання тестів та інших завдань, що потребують Bun. Це дозволяє workflow, що використовує `actions/checkout@v6`, безпосередньо використовувати action, не потребуючи додаткової конфігурації.
+## Огляд
+
+Копіює composite GitHub Action `setup-bun-deps` з каталогу `github-actions/setup-bun-deps/` у цільовий репозиторій (`.github/actions/setup-bun-deps/`). Це забезпечує можливість робочим процесам з правил `ga`, `js` та `text` викликати локально розміщений action (`uses: ./.github/actions/setup-bun-deps`) одразу після виконання `actions/checkout@v6`, використовуючи CLI `npx \@nitra/cursor`.
 
 ## Поведінка
 
-1.  Перевіряє наявність шаблону composite action `action.yml` у каталозі `github-actions/setup-bun-deps/` всередині кореня пакету `@nitra/cursor`.
-2.  Якщо шаблон не знайдено, кидає помилку, вказуючи очікуваний шлях та пропонуючи перевстановити пакет.
-3.  Створює каталог `.github/actions/setup-bun-deps` у цільовому репозиторії, якщо його не існує.
-4.  Зчитує вміст файлу `action.yml` з джерела.
-5.  Записує вміст `action.yml` у файл `action.yml` у цільовому репозиторії. Додає новий рядок в кінці файлу, якщо потрібно.
-6.  Повертає об'єкт, що містить інформацію про успішність запису та повний шлях до створеного файлу.
+1. Перевіряє наявність шаблону composite action у корені встановленого пакету `@nitra/cursor`.
+2. Створює необхідну директорію для composite action у корені цільового репозиторію, ігноруючи шляхи `.github` та `.git`.
+3. Зчитує вміст шаблону composite action.
+4. Записує вміст шаблону у цільовий шлях composite action у корені цільового репозиторію, гарантуючи наявність завершального символу нового рядка.
+5. Повертає підтвердження успішного запису та повний шлях до файлу.
 
 ## Публічний API
 
-syncSetupBunDepsAction — Створює файл з залежностями Bun, використовуючи корінь пакета `@nitra/cursor`.
+syncSetupBunDepsAction — фіксує в `projectRoot` композитну дію з коренем встановленого `@nitra/cursor`.
 
 ## Гарантії поведінки
 
-- Копіює файл `action.yml` з каталогу `github-actions/setup-bun-deps/` у каталог `.github/actions/setup-bun-deps/`.
-- Забезпечує доступність action `setup-bun-deps` для workflow, що використовує `actions/checkout@v6`.
-- Використовує `npx @nitra/cursor` для ініціалізації action.
-- Не враховує наявність checkout runner.
-- Не має кешування.
+- Свідомо пропускає шляхи: `.github`, `.git`.

package/scripts/lib/check-mdc-template-refs.mjs

@@ -45,8 +45,8 @@ async function collectFiles(dir) {
  * @param {string} ruleId basename правила (напр. "security")
  * @returns {Promise<string[]>} відносні шляхи template-файлів без посилань у .mdc
  */
-export async function findMissingMdcRefs(ruleDir, ruleId) {
-  const mdcPath = join(ruleDir, `${ruleId}.mdc`)
+export async function findMissingMdcRefs(ruleDir) {
+  const mdcPath = join(ruleDir, 'main.mdc')
   if (!existsSync(mdcPath)) return []
   const mdc = await readFile(mdcPath, 'utf8')
   const allFiles = await walkTemplateDirs(ruleDir)

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

@@ -3,224 +3,22 @@ type: JS Module
 title: check-mdc-template-refs.mjs
 resource: npm/scripts/lib/check-mdc-template-refs.mjs
 docgen:
-  crc: 17b81322
+  crc: c116210e
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
 ---
 
-Модуль `check-mdc-template-refs.mjs` — це невелика утиліта, призначена для перевірки цілісності посилань між файлом правила `<id>.mdc` та шаблонами, що лежать у підкаталогах `template/` цього самого правила. Він обходить структуру каталогів правила (`fix/<concern>/template/`, `policy/<concern>/template/`), збирає всі знайдені файли й порівнює їхні відносні шляхи з вмістом основного файлу правила `<id>.mdc`. Результатом є перелік шаблонних файлів, на які у `.mdc` немає жодного markdown-посилання, тобто «осиротілі» (orphaned) шаблони.
+## Огляд
 
-Типовий контекст застосування: модуль використовується в утилітах перевірки/лінтингу правил репозиторію (`npm/rules/<id>/`), де `.mdc`-файл описує правило людською мовою й має посилатися на свої шаблони. Якщо шаблон існує, але не згаданий у `.mdc`, цей модуль повідомить про нього, щоб супровідник правила або додав посилання, або видалив зайвий шаблон.
+Визначає список файлів шаблонів, що знаходяться у каталогах `fix` та `policy`, які не є цільовими посиланнями у файлі `<id>.mdc` як markdown link targets. Це дозволяє ідентифікувати ресурси шаблонів, які не були згадані в контексті правила.
 
-Модуль повністю асинхронний (використовує `node:fs/promises`), стандартної залежності від сторонніх бібліотек не має, працює у середовищі Node.js (а також сумісне з Bun) як ES-модуль (`.mjs`).
+## Поведінка
 
-## Експорти / API
+1. Збирає абсолютні шляхи всіх файлів, що знаходяться у каталогах `template` всередині підкаталогів `fix` та `policy` у вказаному каталозі правила.
+2. Зчитує вміст файлу `main.mdc` у каталозі правила.
+3. Фільтрує зібрані шляхи, залишаючи лише ті, які не з'являються у вмісті `main.mdc` у вигляді посилання Markdown (`./<шлях>` або ``).
+4. Повертає відносні шляхи цих незгаданих шаблонних файлів відносно каталогу правила.
 
-Модуль експортує єдину функцію:
+## Гарантії поведінки
 
-- `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`, що насправді є файлом, а не каталогом → пропускається без помилки.
+- Read-only: не виконує операцій запису (ФС/БД).