@nitra/cursor 12.8.3 → 12.8.5

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

@@ -3,305 +3,25 @@ type: JS Module
 title: inline-template-links.mjs
 resource: npm/scripts/lib/inline-template-links.mjs
 docgen:
-  crc: 7726f0ef
+  crc: b659349c
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
 ---
 
-Модуль `inline-template-links.mjs` — допоміжна утиліта для **build-кроку обробки `.mdc`-правил**. Її роль: у текстовому вмісті `.mdc`-документа знайти Markdown-посилання, які ведуть на template-файли (шлях містить сегмент `/template/` або `/templates/`), і **замінити** ці посилання на **інлайн fenced-блоки** з фактичним вмістом target-файлу.
+## Огляд
 
-Простими словами: замість того щоб у згенерованому правилі читач бачив посилання `[конфіг](./templates/package.json.snippet.json)`, він побачить безпосередньо назву реального файлу (`package.json`) і fenced-блок із його вмістом — це робить правило «самодостатнім», без потреби клікати по лінках.
+Цей модуль реалізує механізми вбудовування контенту в текстові документи, використовуючи конфігурації з `package.json.snippet.json` та `package.json`. Він замінює посилання в тексті на вміст файлів-шаблонів, розташованих у каталозі правил, а також на вміст файлів з розширенням .mdc, які не є шаблонами. Функції дозволяють вставляти посилання на шаблони (`inlineTemplateLinks`) та включати вміст Markdown (`inlineMarkdownIncludes`).
 
-Особливості:
+## Поведінка
 
-- Працює асинхронно (`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 замінює посилання в тексті на вбудовані блоки з вмістом файлів, що містять шаблони, якщо ці файли знаходяться в каталозі правил.
+inlineMarkdownIncludes замінює посилання в тексті на вміст файлів з розширенням .mdc, якщо ці файли не є шаблонами.
 
-Модуль експортує єдину функцію `inlineTemplateLinks(text, ruleDir)`.
+## Публічний API
 
-## Експорти / API
+inlineTemplateLinks — Замінює посилання у Markdown, що містять `/template/`, на вбудовані блокові конструкції, зчитуючи вміст з вказаного файлу. Викидає помилку, якщо цільове посилання не знайдено.
+inlineMarkdownIncludes — Замінює посилання у Markdown, що закінчуються на `.mdc` (і не є шляхом `/template/`), на сирий вміст відповідного файлу Markdown. Викидає помилку, якщо цільове посилання не знайдено.
 
-| Експорт               | Тип                                                              | Призначення                                                                                                         |
-| --------------------- | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
-| `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`).
+- Read-only: не виконує операцій запису (ФС/БД).

package/scripts/lib/docs/mirror-parity.md

@@ -3,171 +3,32 @@ type: JS Module
 title: mirror-parity.mjs
 resource: npm/scripts/lib/mirror-parity.mjs
 docgen:
-  crc: 15dc336a
+  crc: 5e366df1
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 90
 ---
 
-Модуль `mirror-parity.mjs` забезпечує перевірку парності (parity) між «дзеркальними» файлами правил Cursor у `.cursor/rules/n-<id>.mdc` та їх канонічними джерелами у `npm/rules/<id>/<id>.mdc`. Ідея така: репозиторій містить два представлення одного й того ж правила:
+## Огляд
 
-- канонічне джерело правила лежить у `npm/rules/<id>/<id>.mdc` (з можливими посиланнями на шаблони у тій самій теці);
-- дзеркало лежить у `.cursor/rules/n-<id>.mdc` і повинно бути результатом застосування трансформу `inlineTemplateLinks` до канону (тобто посилання на шаблони мають бути вставлені «інлайном»).
+Модуль порівнює вміст дзеркал правил (`.cursor/rules/n-<id>.mdc`) з канонічними версіями (`npm/rules/<id>/<id>.mdc`), які містять застосовані трансформації (трансформ, що застосовує `readBundledRuleContent` $\to$ `inlineTemplateLinks`). Він визначає список керованих дзеркал, формує очікуваний вміст для кожного дзеркала та виявляє дрейф — відхилення фактичного вмісту від очікуваного.
 
-Коли канонічний `.mdc` змінюють і забувають регенерувати дзеркало, виникає «дрейф» (drift). Цей модуль:
+## Поведінка
 
-- перелічує керовані дзеркала (ті, для яких знайдено канон);
-- обчислює очікуваний вміст дзеркала через ту саму трансформацію, що і синхронізатор;
-- виявляє ідентифікатори дрейфних правил (де `actual ≠ expected`).
+listManagedMirrors
+Визначає список керованих дзеркал правил, які мають відповідне канонічне джерело у `npm/rules`.
 
-Модуль використовується одночасно і як гард у тестах (очікувано `drift === []`), і для разової регенерації дзеркал. Контекст беклогу — адаптація flow #10.
+expectedMirrorContent
+Формує очікуваний вміст дзеркала, застосовуючи трансформації до канонічного файлу.
 
-## Експорти / API
+findMirrorDrift
+Виявляє ідентифікатори дзеркал, чий фактичний вміст відрізняється від очікуваного вмісту, отриманого з канону.
 
-Модуль експортує три іменовані функції:
+## Публічний API
 
-- `listManagedMirrors(repoRoot)` — синхронна; повертає опис керованих дзеркал.
-- `expectedMirrorContent(canonicalPath)` — асинхронна (повертає `Promise<string>`); обчислює очікуваний вміст дзеркала.
-- `findMirrorDrift(repoRoot)` — асинхронна; повертає масив id правил із дрейфом, відсортований за зростанням.
+listManagedMirrors — перераховує керовані дзеркала, які мають визначене канонічне джерело.
+expectedMirrorContent — визначає бажаний вміст дзеркала, використовуючи канон із вбудованими шаблонами.
+findMirrorDrift — знаходить ідентифікатори дзеркал, у яких фактичний вміст відрізняється від очікуваного.
 
-Жодних дефолтних експортів, побічних ефектів на рівні модуля немає (лише імпорти стандартних модулів і одного локального).
+## Гарантії поведінки
 
-## Функції
-
-### `listManagedMirrors(repoRoot)`
-
-Сигнатура: `function listManagedMirrors(repoRoot: string): { id: string, mirrorPath: string, canonicalPath: string }[]`
-
-Параметри:
-
-- `repoRoot` — абсолютний шлях до кореня репозиторію (директорія, у якій лежать `.cursor/` та `npm/`).
-
-Повертає масив об'єктів-описів дзеркал, де:
-
-- `id` — ідентифікатор правила без префіксу `n-` і без розширення `.mdc` (наприклад, для файлу `n-bun.mdc` → `bun`);
-- `mirrorPath` — абсолютний шлях до файлу дзеркала всередині `.cursor/rules/`;
-- `canonicalPath` — абсолютний шлях до канонічного `.mdc` всередині `npm/rules/<id>/`.
-
-Алгоритм:
-
-1. Будує шлях до `.cursor/rules`.
-2. Якщо такої директорії не існує (`existsSync` false) — повертає порожній масив (раннє повернення, безпечне для свіжих репо).
-3. Зчитує перелік файлів директорії синхронно (`readdirSync`).
-4. Фільтрує файли: повинні починатися з префіксу `'n-'` (константа `MIRROR_PREFIX`) і завершуватися розширенням `'.mdc'` (константа `MDC_EXT`).
-5. Мапить кожен файл у об'єкт із обчисленими шляхами: `id` отримується вирізанням префіксу і розширення (`f.slice(MIRROR_PREFIX.length, -MDC_EXT.length)`).
-6. Залишає лише ті записи, для яких реально існує канонічне джерело `canonicalPath` (друга фільтрація через `existsSync`). Це дозволяє пропускати «зовнішні» дзеркала, які не мають канону в монорепо.
-
-Side effects: лише читання директорії з диску (синхронні `existsSync`, `readdirSync`). Жодних записів, мережевих викликів, мутацій глобального стану.
-
-Помилки: якщо файлова система кине помилку під час `readdirSync` (наприклад, права доступу) — вона прокинеться вгору; для типового сценарію відсутності директорії `.cursor/rules` функція не падає (гард через `existsSync`).
-
-### `expectedMirrorContent(canonicalPath)`
-
-Сигнатура: `function expectedMirrorContent(canonicalPath: string): Promise<string>`
-
-Параметри:
-
-- `canonicalPath` — абсолютний шлях до канонічного `.mdc`-файлу (`npm/rules/<id>/<id>.mdc`).
-
-Повертає `Promise<string>` — очікуваний (нормалізований) текст дзеркала після інлайнінгу шаблонів. Хоча сама функція не використовує `async`/`await`, її результат типізовано як `Promise`, оскільки делегує виклик до `inlineTemplateLinks`, яка є асинхронною (її результат може бути thenable). Це означає, що споживач має `await`-нути повернене значення.
-
-Алгоритм:
-
-1. Синхронно зчитує вміст канонічного файлу як UTF-8 (`readFileSync(canonicalPath, 'utf8')`).
-2. Викликає `inlineTemplateLinks(content, dirname(canonicalPath))`, передаючи прочитаний текст та теку канону як base для розв'язання шляхів до шаблонів.
-3. Повертає результат трансформації.
-
-Side effects: одне читання з диску. Подальша поведінка щодо шаблонів інкапсульована в `inlineTemplateLinks` (див. її документацію). Контракт: цей же самий трансформ застосовує синк, тому очікуваний вміст детермінований по канону.
-
-Помилки: якщо файл за `canonicalPath` не існує або недоступний — `readFileSync` кине помилку. Викличні сторони мають гарантувати існування (`listManagedMirrors` уже фільтрує неіснуючі канони).
-
-### `findMirrorDrift(repoRoot)`
-
-Сигнатура: `async function findMirrorDrift(repoRoot: string): Promise<string[]>`
-
-Параметри:
-
-- `repoRoot` — абсолютний шлях до кореня репозиторію.
-
-Повертає `Promise<string[]>` — відсортований за зростанням масив `id` правил, де дзеркало розійшлося з очікуваним вмістом.
-
-Алгоритм:
-
-1. Заводить порожній масив `drift`.
-2. Послідовно (через `for...of`) обходить усі керовані дзеркала, отримані з `listManagedMirrors(repoRoot)`.
-3. Для кожного дзеркала `m`:
-   - `await`-ить очікуваний вміст через `expectedMirrorContent(m.canonicalPath)`;
-   - синхронно зчитує фактичний вміст файлу дзеркала `readFileSync(m.mirrorPath, 'utf8')`;
-   - якщо стрічки не дорівнюють — додає `m.id` до `drift`.
-4. Повертає `drift.sort()` (лексикографічне сортування).
-
-Side effects: тільки читання з диску. Не записує жодних файлів, не пише в лог.
-
-Зауваження щодо порівняння: рівність стрічок є точною (строге `!==` по UTF-8 тексту). Будь-яка різниця в пробілах, символах кінця рядка чи порядку інлайнених шаблонів буде розцінена як дрейф.
-
-## Залежності
-
-Стандартна бібліотека Node.js:
-
-- `node:fs` — `existsSync`, `readdirSync`, `readFileSync`. Усі виклики синхронні. Імпорт зроблено через `node:`-префікс для явної прив'язки до built-in модуля.
-- `node:path` — `dirname`, `join`. Використовуються для безпечного складання абсолютних шляхів і отримання батьківської теки канону.
-
-Локальні модулі:
-
-- `./inline-template-links.mjs` — імпорт іменованої функції `inlineTemplateLinks(content, baseDir)`. Це той самий трансформ, що його використовує синк дзеркал; саме завдяки спільному використанню досягається консистентність між «гардом дрейфу» і «генератором дзеркал».
-
-Зовнішніх npm-залежностей немає.
-
-Константи на рівні модуля:
-
-- `MIRROR_PREFIX = 'n-'` — префікс імені файлів дзеркал.
-- `MDC_EXT = '.mdc'` — розширення файлів правил Cursor.
-
-## Потік виконання / Використання
-
-Типові сценарії використання модуля:
-
-1. Тест-гард парності (CI). Споживач передає корінь репо й перевіряє, що дрейф порожній:
-
-   ```js
-   import { findMirrorDrift } from './mirror-parity.mjs'
-
-   const drift = await findMirrorDrift(repoRoot)
-   if (drift.length) {
-     throw new Error(`Mirror drift detected for: ${drift.join(', ')}`)
-   }
-   ```
-
-2. Разова регенерація дзеркал. Споживач отримує список керованих дзеркал і для кожного перезаписує файл дзеркала очікуваним вмістом:
-
-   ```js
-   import { writeFileSync } from 'node:fs'
-   import { listManagedMirrors, expectedMirrorContent } from './mirror-parity.mjs'
-
-   for (const m of listManagedMirrors(repoRoot)) {
-     const expected = await expectedMirrorContent(m.canonicalPath)
-     writeFileSync(m.mirrorPath, expected)
-   }
-   ```
-
-   (Сам модуль `mirror-parity.mjs` записів не виконує — це задача викличного скрипта.)
-
-Внутрішній потік виконання `findMirrorDrift`:
-
-1. Виклик `listManagedMirrors(repoRoot)`:
-   - перевірка існування `.cursor/rules`;
-   - читання списку файлів;
-   - фільтрація за префіксом `n-` і розширенням `.mdc`;
-   - обчислення `id`, `mirrorPath`, `canonicalPath`;
-   - відкидання дзеркал без канону.
-2. Послідовний обхід отриманих описів:
-   - читання канону → `inlineTemplateLinks` → очікуваний текст;
-   - читання дзеркала → порівняння;
-   - накопичення id з дрейфом.
-3. Сортування результату та повернення.
-
-Контрактна гарантія: якщо синк використовує ту ж саму функцію `inlineTemplateLinks` для генерації дзеркал, то регенерація закриває будь-який дрейф, виявлений `findMirrorDrift`. Якщо дрейф виявлено — він завжди вказує на людську помилку (зміна канону без регенерації) або на розбіжність версій трансформу.
-
-Обмеження:
-
-- Обхід послідовний (без `Promise.all`) — простіший контракт по помилках, але повільніший на великих наборах правил. Зважаючи на типову кількість правил у `.cursor/rules`, це не критично.
-- Усі читання файлів синхронні, попри асинхронну сигнатуру `findMirrorDrift` — асинхронність зумовлена тільки інтерфейсом `inlineTemplateLinks`.
-- Префікс `n-` зашитий константою — додавання інших префіксів дзеркал вимагатиме зміни модуля.
-- Зовнішні дзеркала (без канону в `npm/rules/<id>/`) автоматично пропускаються; модуль не повідомляє про них окремо.
+- Read-only: не виконує операцій запису (ФС/БД).

package/scripts/lib/docs/rule-meta.md

@@ -3,36 +3,33 @@ type: JS Module
 title: rule-meta.mjs
 resource: npm/scripts/lib/rule-meta.mjs
 docgen:
-  crc: fa5ca866
+  crc: 36aea8cb
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
 ---
 
-Цей файл парсує метадані правил npm/rules/<id>/meta.json для автоматичного виявлення проблемних місць у коді. Він визначає, коли правило має бути активним, використовуючи різні специфікації, такі як завжди-ввімкнене правило, правило, яке активується після виявлення залежностей, або правило, яке активується на основі glob-шаблонів чи незводимих предикатів. Це дозволяє системі динамічно визначати та застосовувати правила, не потребуючи явного налаштування.
+## Огляд
+
+Парсер інтерпретує метадані правил, що знаходяться у `npm/rules/<id>/meta.json`. Він реалізує data-driven логіку для визначення умов активації кожного детектора. Специфікації активації (`auto`) нормалізуються на основі вмісту `meta.json`, підтримуючи чотири типи: константа `RULE_ALWAYS` ("завжди"), залежності від інших правил, шаблони за допомогою `glob`, або незводимі предикати. Парсер не виконує операцій запису у файлову систему чи бази даних і забезпечує безпечну роботу, перехоплюючи помилки.
 
 ## Поведінка
 
-`RULE_ALWAYS`: визначає літерал для активації правила "завжди".
-`parseRuleAutoSpec`: нормалізує значення `meta.json.auto` у дискриміновану форму.
-`parseRuleLintPhase`: нормалізує значення `meta.json.lint` у фазу lint.
-`readRuleMetaRaw`: читає та парсить `meta.json` одного правила, повертаючи об’єкт або `null`.
+RULE_ALWAYS — константа, що позначає безумовну активацію правила.
+parseRuleAutoSpec — Нормалізує значення поля `auto` з метаданих правила у дискриміновану специфікацію активації.
+parseRuleLintSpec — Нормалізує значення поля `lint` з метаданих правила у специфікацію області застосування детектора.
+readRuleMetaRaw — Читає та парсить вміст `main.json` з каталогу правила, повертаючи його як об'єкт або `null` у разі помилки чи відсутності файлу.
 
 ## Публічний API
 
-- RULE_ALWAYS — Активує правило.
-- parseRuleAutoSpec — Перетворює значення `meta.json.auto` на конкретну опцію.
-- parseRuleLintPhase — Перетворює значення `meta.json.lint` на фазу lint.
-- readRuleMetaRaw — Зчитує та аналізує файл `meta.json` правила.
+RULE_ALWAYS — константа, що вказує на безумовну активацію.
+parseRuleAutoSpec — перетворює налаштування автоматичного визначення правил з `meta.json` у структурований формат.
+parseRuleLintSpec — перетворює налаштування лінтування з `meta.json` у визначення області дії детектора.
+"per-file" — визначає, що детектор працює з окремими зміненими файлами (порівняння змін з оригіналом).
+"full" — вказує на повний, нероздільний аналіз між усіма файлами (активується лише при використанні прапорця `--full` або в CI).
+readRuleMetaRaw — зчитує та обробляє метадані одного правила з файлу `meta.json`.
 
 ## Гарантії поведінки
 
-- `RULE_ALWAYS` повертає `true` якщо правило активне.
-- `parseRuleAutoSpec` повертає `true` якщо специфікація правила успішно розібрана.
-- `parseRuleAutoSpec` повертає `false` якщо специфікація правила не може бути розібрана.
-- `parseRuleLintPhase` повертає `true` якщо правило успішно розібрано на етапі linting.
-- `parseRuleLintPhase` повертає `false` якщо правило не може бути розібрано на етапі linting.
-- `readRuleMetaRaw` повертає `true` якщо метадані правила успішно прочитані.
-- `readRuleMetaRaw` повертає `false` якщо метадані правила не можуть бути прочитані.
-- У разі невдачі, функція повертає `false` або `null`.
-- Функції не кидають винятків.
-- Немає кешування.
-- Немає гарантій щодо стану файлів або каталогів.
-- Поля `worktree` правила не використовуються.
+- Read-only: не виконує операцій запису (ФС/БД).
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).
+- За певних помилок повертає порожнє значення (напр. `null`) замість винятку.

package/scripts/lib/docs/run-rule.md

@@ -3,27 +3,27 @@ type: JS Module
 title: run-rule.mjs
 resource: npm/scripts/lib/run-rule.mjs
 docgen:
-  crc: 27060842
-  score: 95
+  crc: 7d0585e1
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 90
 ---
 
-Файл слугує оркестратором правила. Він координує виконання перевірок, включаючи перевірку гейту, JS-концернів та policy-концернів.
+## Огляд
+
+Файл оркеструє виконання одного правила під CLI `fix`. Він послідовно застосовує гейт `applies` з `js/applies.mjs` для визначення придатності правила. Якщо гейт повертає `false`, правило не застосовується. Далі виконуються JS-концерни та Policy-концерни в алфавітному порядку. Резолвер `resolveTargetFiles` ділить кеш між концернами. Кожен concern створює власний репортер, а їхні exit-коди OR-уються в єдиний контракт, що забезпечує 0/1 результат для правила. Оркестратор спирається на конфігурації `target.json` та `.n-cursor.json`.
 
 ## Поведінка
 
-runTemplateSubsetConcern
-Перевіряє відповідність фактичного файлу канонічному шаблону.
+runTemplateSubsetConcern виконує перевірку концерну, де канон визначається сніпетом у `target.json`, звіряючи його з актуальними файлами-таргетами.
 
-runRule
-Оркеструє виконання правила, включаючи перевірку гейту, JS-концернів та policy-концернів.
+runRule оркеструє виконання одного правила, послідовно застосовуючи applies-гейт, виконуючи JS-концерни та запускаючи policy-концерни, а також перевіряючи відсутність markdown-посилань.
 
 ## Публічний API
 
-- runTemplateSubsetConcern — Snippet-driven перевірка концерну (`target.json:"check":"template"`): звіряє канон з фактичним файлом за допомогою глибокого підмножинного перевірки. Усі канонічні поля/елементи обов'язкові, зайві дозволені. Масиви співпадають за наявністю (незалежно від порядку). Зміна сніпета негайно впливає на примусовість.
-- runRule — Запускає одне правило: applies-гейт → JS-концерни → policy-концерни.
+runTemplateSubsetConcern — Порівнює фактичний файл із канонічним шаблоном (з `target.json`) для перевірки, чи всі обов'язкові елементи присутні, дозволяючи додаткові.
+runRule — Виконує окреме правило, яке проходить через перевірки застосовності, JavaScript-концерни та політики.
 
 ## Гарантії поведінки
 
-- Read-only: файл не виконує операцій запису у файлову систему.
+- Read-only: не виконує операцій запису (ФС/БД).
 - Кешує результати в межах одного прогону.
-- Не звертається до мережі.