npm - @nitra/cursor - Versions diffs - 12.8.2 → 12.8.4 - Mend

@nitra/cursor 12.8.2 → 12.8.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (136) hide show

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

@@ -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: не виконує операцій запису (ФС/БД).

package/scripts/lib/docs/gha-workflow.md CHANGED Viewed

@@ -3,7 +3,7 @@ type: JS Module
 title: gha-workflow.mjs
 resource: npm/scripts/lib/gha-workflow.mjs
 docgen:
-  crc: d73b42f2
+  crc: 952d34d4
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 100
 ---

package/scripts/lib/docs/index.md CHANGED Viewed

@@ -6,40 +6,40 @@ resource: npm/scripts/lib/
 # npm/scripts/lib
-| Файл                                                                        | Тип       |
-| --------------------------------------------------------------------------- | --------- |
-| [assert-project-root.mjs](assert-project-root.md)                           | JS Module |
-| [changed-files.mjs](changed-files.md)                                       | JS Module |
-| [check-mdc-template-refs.mjs](check-mdc-template-refs.md)                   | JS Module |
-| [check-reporter.mjs](check-reporter.md)                                     | JS Module |
-| [diff-added-lines.mjs](diff-added-lines.md)                                 | JS Module |
+| Файл | Тип |
+|---|---|
+| [assert-project-root.mjs](assert-project-root.md) | JS Module |
+| [changed-files.mjs](changed-files.md) | JS Module |
+| [check-mdc-template-refs.mjs](check-mdc-template-refs.md) | JS Module |
+| [check-reporter.mjs](check-reporter.md) | JS Module |
+| [diff-added-lines.mjs](diff-added-lines.md) | JS Module |
 | [discover-check-rules-from-cursor.mjs](discover-check-rules-from-cursor.md) | JS Module |
-| [discover-checkable-rules.mjs](discover-checkable-rules.md)                 | JS Module |
-| [ensure-tool.mjs](ensure-tool.md)                                           | JS Module |
-| [generated-markdown.mjs](generated-markdown.md)                             | JS Module |
-| [gha-workflow.mjs](gha-workflow.md)                                         | JS Module |
-| [inline-template-links.mjs](inline-template-links.md)                       | JS Module |
-| [list-project-rules-mdc.mjs](list-project-rules-mdc.md)                     | JS Module |
-| [list-rule-ids.mjs](list-rule-ids.md)                                       | JS Module |
-| [load-cursor-config.mjs](load-cursor-config.md)                             | JS Module |
-| [mirror-parity.mjs](mirror-parity.md)                                       | JS Module |
-| [read-n-cursor-config-lite.mjs](read-n-cursor-config-lite.md)               | JS Module |
-| [resolve-target-files.mjs](resolve-target-files.md)                         | JS Module |
-| [root-notice.mjs](root-notice.md)                                           | JS Module |
-| [rule-meta-helpers.mjs](rule-meta-helpers.md)                               | JS Module |
-| [rule-meta.mjs](rule-meta.md)                                               | JS Module |
-| [rule-predicates.mjs](rule-predicates.md)                                   | JS Module |
-| [run-conftest-batch.mjs](run-conftest-batch.md)                             | JS Module |
-| [run-lint-step.mjs](run-lint-step.md)                                       | JS Module |
-| [run-lint.mjs](run-lint.md)                                                 | JS Module |
-| [run-rule-cli.mjs](run-rule-cli.md)                                         | JS Module |
-| [run-rule.mjs](run-rule.md)                                                 | JS Module |
-| [run-standard-lint.mjs](run-standard-lint.md)                               | JS Module |
-| [run-standard-rule.mjs](run-standard-rule.md)                               | JS Module |
-| [skill-meta.mjs](skill-meta.md)                                             | JS Module |
-| [sync-gitignore-worktree.mjs](sync-gitignore-worktree.md)                   | JS Module |
-| [template.mjs](template.md)                                                 | JS Module |
-| [timing-summary.mjs](timing-summary.md)                                     | JS Module |
-| [workspaces.mjs](workspaces.md)                                             | JS Module |
-| [worktree-notice.mjs](worktree-notice.md)                                   | JS Module |
-| [worktree.mjs](worktree.md)                                                 | JS Module |
+| [discover-checkable-rules.mjs](discover-checkable-rules.md) | JS Module |
+| [ensure-tool.mjs](ensure-tool.md) | JS Module |
+| [generated-markdown.mjs](generated-markdown.md) | JS Module |
+| [gha-workflow.mjs](gha-workflow.md) | JS Module |
+| [inline-template-links.mjs](inline-template-links.md) | JS Module |
+| [list-project-rules-mdc.mjs](list-project-rules-mdc.md) | JS Module |
+| [list-rule-ids.mjs](list-rule-ids.md) | JS Module |
+| [load-cursor-config.mjs](load-cursor-config.md) | JS Module |
+| [mirror-parity.mjs](mirror-parity.md) | JS Module |
+| [read-n-cursor-config-lite.mjs](read-n-cursor-config-lite.md) | JS Module |
+| [resolve-target-files.mjs](resolve-target-files.md) | JS Module |
+| [root-notice.mjs](root-notice.md) | JS Module |
+| [rule-meta-helpers.mjs](rule-meta-helpers.md) | JS Module |
+| [rule-meta.mjs](rule-meta.md) | JS Module |
+| [rule-predicates.mjs](rule-predicates.md) | JS Module |
+| [run-conftest-batch.mjs](run-conftest-batch.md) | JS Module |
+| [run-lint-step.mjs](run-lint-step.md) | JS Module |
+| [run-lint.mjs](run-lint.md) | JS Module |
+| [run-rule-cli.mjs](run-rule-cli.md) | JS Module |
+| [run-rule.mjs](run-rule.md) | JS Module |
+| [run-standard-lint.mjs](run-standard-lint.md) | JS Module |
+| [run-standard-rule.mjs](run-standard-rule.md) | JS Module |
+| [skill-meta.mjs](skill-meta.md) | JS Module |
+| [sync-gitignore-worktree.mjs](sync-gitignore-worktree.md) | JS Module |
+| [template.mjs](template.md) | JS Module |
+| [timing-summary.mjs](timing-summary.md) | JS Module |
+| [workspaces.mjs](workspaces.md) | JS Module |
+| [worktree-notice.mjs](worktree-notice.md) | JS Module |
+| [worktree.mjs](worktree.md) | JS Module |

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

@@ -3,171 +3,32 @@ type: JS Module
 title: mirror-parity.mjs
 resource: npm/scripts/lib/mirror-parity.mjs
 docgen:
-  crc: 15dc336a
+  crc: d2140a00
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
 ---
-Модуль `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` до канону (тобто посилання на шаблони мають бути вставлені «інлайном»).
+Модуль забезпечує паралельність (parity) дзеркал правил. Він порівнює вміст дзеркала `.cursor/rules/n-<id>.mdc` з канонічним вмістом `npm/rules/<id>/<id>.mdc`, який містить вбудовані шаблони (inlined-шаблони). Це гарантує, що локальні копії правил відповідають централізованим, трансформованим версіям, виявляючи дрейф, що виникає при зміні канонічного `.mdc` без регенерації дзеркала.
-Коли канонічний `.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 CHANGED Viewed

@@ -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`) замість винятку.