@7n/rules 1.0.0

package/scripts/lib/docs/generated-markdown.md

@@ -0,0 +1,279 @@
+---
+type: JS Module
+title: generated-markdown.mjs
+resource: npm/scripts/lib/generated-markdown.mjs
+docgen:
+  crc: 8ac3c916
+---
+
+Модуль `generated-markdown.mjs` містить набір чистих утиліт для генерації згенерованих маркдаун-файлів (зокрема `AGENTS.md` та `CLAUDE.md`) у межах CLI `n-rules`. Він виконує дві основні задачі:
+
+1. Розгортає Mustache-подібні блоки `{{#section}}…{{/section}}` із простою підстановкою одного поля `{{prop}}` для кожного елемента переданого масиву.
+2. Нормалізує підсумковий markdown, не лишаючи послідовностей із трьох і більше `\n` (тобто двох і більше порожніх рядків поспіль), щоб результат відповідав правилу markdownlint **MD012** (no multiple blank lines).
+
+Усі функції модуля — суто функціональні (без побічних ефектів, без I/O, без залежностей від глобального стану). Вхід — рядки та звичайні JS-обʼєкти, вихід — рядок.
+
+Файл реалізовано як ES-модуль (ESM), розширення `.mjs`, експорти `export function`.
+
+## Експорти / API
+
+Модуль експортує чотири іменовані функції:
+
+| Експорт                        | Тип                                                                                                                          | Призначення                                                                                                                   |
+| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| `collapseMultipleBlankLines`   | `(text: string) => string`                                                                                                   | Згортає 3+ послідовних `\n` до рівно `\n\n`.                                                                                  |
+| `expandMustacheSection`        | `(template: string, section: string, items: Record<string,string>[], prop: string) => string`                                | Розгортає блок `{{#section}}…{{/section}}` для кожного елемента масиву `items`, підставляючи `item[prop]` замість `{{prop}}`. |
+| `renderAgentsTemplate`         | `(templateText: string, mdcBasenames: string[], skillItems: { name: string }[], commandItems: { name: string }[]) => string` | Високорівневий рендерер шаблону `AGENTS.template.md`: підставляє списки правил, скілів і команд та нормалізує порожні рядки.  |
+| `formatGeneratedMarkdownLines` | `(lines: string[]) => string`                                                                                                | Збирає масив рядків у єдиний markdown-документ із гарантованим завершальним `\n` і без подвійних порожніх рядків.             |
+
+Усі функції детерміновані: для однакових входів повертають однаковий вихід.
+
+## Функції
+
+### `collapseMultipleBlankLines(text)`
+
+**Сигнатура**
+
+```js
+export function collapseMultipleBlankLines(text)
+```
+
+**Параметри**
+
+- `text` (`string`) — вихідний markdown або будь-який текст. Якщо передано не-рядок, він буде явно скастовано через `String(text)`.
+
+**Повертає**
+
+- `string` — той самий текст, у якому всі послідовності з трьох і більше `\n` замінено на рівно два `\n` (тобто між блоками лишається не більше ніж один порожній рядок).
+
+**Алгоритм**
+
+1. Виконує `String(text)` — захист від нерядкового входу (наприклад, `null`, `undefined`, число, обʼєкт).
+2. Викликає `replaceAll(/\n{3,}/g, '\n\n')` — глобальна заміна всіх послідовностей `\n{3,}` на `\n\n`.
+
+**Side effects**
+
+- Немає. Функція чиста.
+
+**Особливості**
+
+- Послідовності `\n\n` (один порожній рядок) залишаються без змін.
+- Працює лише з символом `\n`; `\r\n` (CRLF) не нормалізується явно — якщо вхід містить CRLF, регулярка не спрацює на парах `\r\n\r\n\r\n` як на трьох `\n`.
+
+### `expandMustacheSection(template, section, items, prop)`
+
+**Сигнатура**
+
+```js
+export function expandMustacheSection(template, section, items, prop)
+```
+
+**Параметри**
+
+- `template` (`string`) — вихідний текст шаблону, що може містити нуль чи більше блоків `{{#section}}…{{/section}}`.
+- `section` (`string`) — імʼя секції (наприклад, `services`, `skills`, `commands`). Підставляється у відкриваючий тег `{{#section}}` і закриваючий `{{/section}}`.
+- `items` (`Record<string, string>[]`) — масив елементів-обʼєктів. Для кожного елемента тіло секції повторюється один раз.
+- `prop` (`string`) — імʼя поля, значення якого підставляється замість `{{prop}}` у тілі секції. Значення приводиться до рядка через `String(item[prop])`.
+
+**Повертає**
+
+- `string` — текст шаблону, у якому всі знайдені блоки `{{#section}}…{{/section}}` замінено на згенерований вміст. Якщо блоків немає — повертає вхідний рядок без змін.
+
+**Алгоритм**
+
+1. Будує константи `open = '{{#${section}}}'`, `close = '{{/${section}}}'`, `placeholder = '{{${prop}}}'`.
+2. У циклі шукає першу позицію `start = indexOf(open)` та `end = indexOf(close)` у поточному значенні `result`.
+3. Поки знайдено валідну пару (`start !== -1 && end !== -1 && end > start`):
+   - Витягує `inner = result.slice(start + open.length, end).trim()` — тіло секції без обрамних пробілів/переносів.
+   - Для кожного `item` з `items` будує рядок `inner.split(placeholder).join(String(item[prop]))` — повна заміна всіх входжень `placeholder` на значення поля.
+   - Зʼєднує всі рендери одним `\n` (без зайвих порожніх рядків між елементами).
+   - Підставляє згенерований текст замість усього блоку: `result = result.slice(0, start) + rendered + result.slice(end + close.length)`.
+   - Перераховує `start` і `end` для наступної ітерації.
+4. Повертає `result`.
+
+**Side effects**
+
+- Немає. Функція чиста.
+
+**Особливості й обмеження**
+
+- Блок підставляється лише за умови `end > start`, тобто закриття має йти після відкриття; вкладені секції з тим самим імʼям не підтримуються.
+- `trim()` тіла секції видаляє пробіли/переноси на початку й у кінці — це навмисно, щоб не лишати пустого рядка на стику з оточуючим markdown.
+- Plаceholder `{{prop}}` замінюється через `split(...).join(...)` — це еквівалентно глобальній заміні без побудови RegExp.
+- Якщо `items` порожній — блок замінюється на порожній рядок (`[].join('\n') === ''`).
+- Підстановка `prop` єдина на блок: модуль не підтримує кілька різних змінних усередині одного блоку.
+
+### `renderAgentsTemplate(templateText, mdcBasenames, skillItems, commandItems)`
+
+**Сигнатура**
+
+```js
+export function renderAgentsTemplate(templateText, mdcBasenames, skillItems, commandItems)
+```
+
+**Параметри**
+
+- `templateText` (`string`) — повний вміст файлу `AGENTS.template.md` із Mustache-блоками `{{#services}}`, `{{#skills}}`, `{{#commands}}` (кожен зі своїм `{{name}}` усередині).
+- `mdcBasenames` (`string[]`) — масив імен файлів правил `*.mdc` з каталогу `.cursor/rules` (саме базові імена, без шляху).
+- `skillItems` (`{ name: string }[]`) — готові рядки для секції Skills у форматі `{ name: '…' }` (зазвичай вже включають bullet/опис).
+- `commandItems` (`{ name: string }[]`) — готові рядки для секції commands у форматі `{ name: '…' }`.
+
+**Повертає**
+
+- `string` — готовий вміст `AGENTS.md` із розгорнутими секціями та згорнутими подвійними порожніми рядками.
+
+**Алгоритм**
+
+1. Перетворює `mdcBasenames` на `serviceItems` виду `{ name: '- .cursor/rules/${mdcName}' }` — додає префікс маркера списку й каталог `.cursor/rules/`.
+2. Послідовно викликає `expandMustacheSection` для трьох секцій:
+   - `services` із `serviceItems` і ключем `name`;
+   - `skills` із `skillItems` і ключем `name`;
+   - `commands` із `commandItems` і ключем `name`.
+3. Передає результат у `collapseMultipleBlankLines` і повертає його.
+
+**Side effects**
+
+- Немає. Файлову систему не читає й не пише — лише трансформує переданий рядок.
+
+**Особливості**
+
+- Ключ `name` зашитий у функцію — структура `skillItems` і `commandItems` має містити саме поле `name`.
+- Кожен елемент `mdcBasenames` форматується як bullet списку (`- ...`) у єдиному стилі.
+
+### `formatGeneratedMarkdownLines(lines)`
+
+**Сигнатура**
+
+```js
+export function formatGeneratedMarkdownLines(lines)
+```
+
+**Параметри**
+
+- `lines` (`string[]`) — масив рядків markdown-документа. Кожен елемент — окремий «рядок» (може бути порожнім або містити кілька логічних рядків).
+
+**Повертає**
+
+- `string` — підсумковий текст, у якому:
+  - елементи `lines` зʼєднано через `\n`;
+  - послідовності з 3+ `\n` згорнуто до `\n\n` (через `collapseMultipleBlankLines`);
+  - гарантовано додано завершальний `\n`, якщо його не було.
+
+**Алгоритм**
+
+1. `text = lines.join('\n')` — конкатенація через символ переносу рядка.
+2. `collapsed = collapseMultipleBlankLines(text)` — нормалізація порожніх рядків.
+3. Якщо `collapsed.endsWith('\n')` — повернути як є; інакше повернути `collapsed + '\n'`.
+
+**Side effects**
+
+- Немає.
+
+**Особливості**
+
+- Завершальний `\n` гарантує, що згенерований файл закінчується новим рядком (вимога багатьох лінтерів і POSIX-конвенції).
+- Жодних відступів чи табуляцій функція не корегує — лише вертикальну щільність.
+
+## Залежності
+
+### Зовнішні
+
+- Жодних. Модуль не імпортує нічого ні з `node:*`, ні з npm-пакетів, ні з інших файлів проєкту.
+
+### Внутрішні (між функціями модуля)
+
+- `renderAgentsTemplate` використовує `expandMustacheSection` (тричі) і `collapseMultipleBlankLines` (один раз).
+- `formatGeneratedMarkdownLines` використовує `collapseMultipleBlankLines`.
+- `collapseMultipleBlankLines` і `expandMustacheSection` — незалежні низькорівневі будівельні блоки.
+
+### Runtime
+
+- ECMAScript із підтримкою:
+  - `String.prototype.replaceAll` (Node.js ≥ 15);
+  - класичних `String.prototype.indexOf`, `slice`, `split`, `join`, `trim`, `endsWith`;
+  - синтаксису ESM (`export function`).
+
+## Потік виконання / Використання
+
+Типовий потік генерації `AGENTS.md`:
+
+1. Викликач (CLI `n-rules`) читає шаблон `AGENTS.template.md` з файлової системи.
+2. Збирає три масиви даних:
+   - список `*.mdc`-файлів із `.cursor/rules` (через `fs.readdir` або еквівалент);
+   - метадані скілів (`name` уже з bullet/описом);
+   - метадані команд (`name` уже з bullet/описом).
+3. Викликає `renderAgentsTemplate(templateText, mdcBasenames, skillItems, commandItems)`.
+4. Записує отриманий рядок у файл `AGENTS.md` (наприклад, через `fs.writeFile`).
+
+Типовий потік генерації багаторядкового документа (наприклад, `CLAUDE.md`):
+
+1. Викликач формує масив рядків `lines` — заголовки, абзаци, bullet-и тощо. Між логічними секціями може лишатися кілька порожніх рядків.
+2. Викликає `formatGeneratedMarkdownLines(lines)` — отримує цілісний документ із чистими стиками секцій та фінальним `\n`.
+3. Записує результат у файл.
+
+Приклад використання `expandMustacheSection` ізольовано:
+
+```js
+import { expandMustacheSection } from './generated-markdown.mjs'
+
+const tpl = '# Rules\n{{#services}}- {{name}}\n{{/services}}\nEnd'
+const out = expandMustacheSection(tpl, 'services', [{ name: 'a.mdc' }, { name: 'b.mdc' }], 'name')
+// out === '# Rules\n- a.mdc\n- b.mdc\nEnd'
+```
+
+Приклад використання `collapseMultipleBlankLines`:
+
+```js
+import { collapseMultipleBlankLines } from './generated-markdown.mjs'
+
+const cleaned = collapseMultipleBlankLines('A\n\n\n\nB')
+// cleaned === 'A\n\nB'
+```
+
+Приклад використання `formatGeneratedMarkdownLines`:
+
+```js
+import { formatGeneratedMarkdownLines } from './generated-markdown.mjs'
+
+const md = formatGeneratedMarkdownLines(['# Title', '', '', '', 'Body'])
+// md === '# Title\n\nBody\n'
+```
+
+## Rebuild Test
+
+Контрольний приклад для перевірки коректності модуля після рефакторингу:
+
+Дано шаблон:
+
+```text
+# Agents
+
+## Services
+{{#services}}
+{{name}}
+{{/services}}
+
+## Skills
+{{#skills}}
+{{name}}
+{{/skills}}
+
+## Commands
+{{#commands}}
+{{name}}
+{{/commands}}
+```
+
+і виклик:
+
+```js
+renderAgentsTemplate(template, ['n-bun.mdc', 'n-vue.mdc'], [{ name: '- /n-fix — fix' }], [{ name: '- /n-lint — lint' }])
+```
+
+Очікувані властивості результату:
+
+- секція `services` містить рядки `- .cursor/rules/n-bun.mdc` і `- .cursor/rules/n-vue.mdc`, розділені одним `\n`;
+- секція `skills` містить рядок `- /n-fix — fix`;
+- секція `commands` містить рядок `- /n-lint — lint`;
+- ніде немає трьох поспіль `\n` (тобто не зʼявляються два порожніх рядки підряд);
+- виклик `formatGeneratedMarkdownLines(result.split('\n'))` повертає той самий зміст із гарантованим завершальним `\n`.

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

@@ -0,0 +1,38 @@
+---
+type: JS Module
+title: gha-workflow.mjs
+resource: npm/scripts/lib/gha-workflow.mjs
+docgen:
+  crc: 6bec44bb
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+---
+
+Надає функції для структурного аналізу конфігурацій GitHub Actions workflow (`.yml`). Дозволяє парсити YAML, витягувати значення з кроків, зокрема `uses:` та `run:`, а також перевіряти відповідність структури workflow певним вимогам. Це забезпечує цілеспрямований аналіз конфігурацій, замінюючи пошук підрядків у сирому тексті.
+
+## Поведінка
+
+parseWorkflowYaml парсить вміст workflow YAML у об'єкт, повертаючи `null` у разі синтаксичної помилки.
+flattenWorkflowSteps збирає плоский список усіх кроків з усіх job'ів workflow, додаючи метадані про job та індекс кроку.
+getStepUses отримує значення `uses` для заданого кроку.
+getStepRun отримує текст команди з поля `run` заданого кроку, об'єднуючи багаторядкові значення.
+eventPathsIncludeExact перевіряє, чи містить `on.push.paths` або `on.pull_request.paths` точне значення шляху.
+verifyLintJsWorkflowStructure перевіряє структуру workflow для відповідності вимогам, зокрема наявність `actions/checkout@v6` з `persist-credentials: false`, використання `setup-bun-deps` та наявність команд `bunx oxlint`, `bunx eslint .`, `bunx jscpd .` у кроках `run`.
+anyRunStepIncludes перевіряє, чи містить хоча б один `run` будь-якого кроку підрядок, який вказує на певний інструмент.
+
+## Публічний API
+
+parseWorkflowYaml — перетворює YAML-файл робочого процесу у структурований об'єкт; повертає `null` при помилці синтаксису.
+flattenWorkflowSteps — об'єднує всі кроки, визначені у всіх завданнях.
+getStepUses — отримує значення, вказане у полі `uses:` для кроку.
+getStepRun — отримує команду, яку виконує крок (може бути одним або багатьма рядками).
+eventPathsIncludeExact — визначає, чи містить список шляхів події (push або pull_request) точне збігання.
+verifyLintJsWorkflowStructure — перевіряє наявність необхідних компонентів у файлі `lint-js.yml` (наприклад, `checkout@v6`, `persist-credentials`, `setup-bun-deps`, виконання команд).
+anyRunStepIncludes — виявляє, чи містить будь-який рядок виконання (`run`) певний підрядок.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).
+- За певних помилок повертає порожнє значення (напр. `null`) замість винятку.
+- Свідомо пропускає шляхи: `.github`, `.git`.

package/scripts/lib/docs/index.md

@@ -0,0 +1,40 @@
+---
+type: Directory Index
+title: npm/scripts/lib
+resource: npm/scripts/lib/
+---
+
+| Файл                                                                        | Тип       |
+| --------------------------------------------------------------------------- | --------- |
+| [assert-project-root.mjs](assert-project-root.md)                           | JS Module |
+| [blue-oak.mjs](blue-oak.md)                                                 | JS Module |
+| [changed-files.mjs](changed-files.md)                                       | JS Module |
+| [check-reporter.mjs](check-reporter.md)                                     | JS Module |
+| [collect-test-files.mjs](collect-test-files.md)                             | JS Module |
+| [concern-meta.mjs](concern-meta.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-rules-config-lite.mjs](read-n-rules-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-standard-lint.mjs](run-standard-lint.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 |

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

@@ -0,0 +1,25 @@
+---
+type: JS Module
+title: inline-template-links.mjs
+resource: npm/scripts/lib/inline-template-links.mjs
+docgen:
+  crc: 35230d2d
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+---
+
+Модуль збагачує текстовий контент, використовуючи конфігурації з package.json.snippet.json та package.json. Функція inlineTemplateLinks замінює текстові посилання на шаблони вбудованими блоками, якщо відповідні файли знаходяться у директорії правил. Функція appendDiscoveredMdcFiles доповнює текст вмістом усіх знайдених файлів `.mdc` з піддиректорій `js/` та `policy/` у директорії правил.
+
+## Поведінка
+
+inlineTemplateLinks замінює посилання на шаблони в тексті на вбудовані блоки з вмістом файлу, якщо ці файли існують у вказаній директорії правил.
+appendDiscoveredMdcFiles додає до кінця тексту вміст усіх знайдених файлів `.mdc` з піддиректорій `js/` та `policy/` у директорії правил.
+
+## Публічний API
+
+inlineTemplateLinks — Замінює посилання на шаблони в Markdown на вбудовані блоки, якщо шлях містить `/template/`. Помилка виникає, якщо цільовий файл посилання відсутній.
+appendDiscoveredMdcFiles — Додає всі знайдені файли `.mdc` з папок `js/` та `policy/<concern>/`. Файли з `js/` йдуть першими, а потім файли з підпапок `policy/<concern>/` (у алфавітному порядку за `concern`, а потім за назвою файлу).
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).

package/scripts/lib/docs/list-project-rules-mdc.md

@@ -0,0 +1,27 @@
+---
+type: JS Module
+title: list-project-rules-mdc.mjs
+resource: npm/scripts/lib/list-project-rules-mdc.mjs
+docgen:
+  crc: 7125782d
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+---
+
+## Огляд
+
+Цей модуль визначає шлях до правил у проєкті-споживачі, що константою експортується як CURSOR_RULES_DIR=".cursor/rules". Він надає відсортований список імен файлів `.mdc` з каталогу правил. Це дозволяє розділити логіку диспетчеризації командного інтерфейсу та логіку перевірки конформності. Функція зчитує та повертає список файлів, якщо каталог правил існує.
+
+## Поведінка
+
+CURSOR_RULES_DIR — Вказує на каталог правил у проєкті-споживачі.
+listProjectRulesMdcFiles — Повертає відсортований список імен файлів `.mdc` з каталогу правил проєкту-споживача, якщо цей каталог існує.
+
+## Публічний API
+
+CURSOR_RULES_DIR — Шлях до каталогу правил у проєкті-споживачі.
+listProjectRulesMdcFiles — Збирає список файлів MDC, що містять правила проєкту.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).

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

@@ -0,0 +1,25 @@
+---
+type: JS Module
+title: list-rule-ids.mjs
+resource: npm/scripts/lib/list-rule-ids.mjs
+docgen:
+  crc: d8b3ea73
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+---
+
+Перебирає директорії у `rules/` та фільтрує їх, вибираючи лише ті, що містять єдиний канонічний entrypoint (`rules/<id>/main.mjs`), згідно з ADR 2026-06-21. Функція повертає список ідентифікаторів правил, які відповідають цьому канону. Операція є лише для читання файлової системи.
+
+## Поведінка
+
+1. Зчитує список усіх каталогів у директорії, що містить правила.
+2. Фільтрує цей список, залишаючи лише каталоги, які не починаються з крапки.
+3. Для кожного каталогу перевіряє, чи існує у ньому файл `main.mjs`.
+4. Фільтрує список, залишаючи лише ті каталоги, які містять файл `main.mjs`.
+5. Якщо надано фільтр, додатково фільтрує список, залишаючи лише той ID, що збігається з фільтром.
+6. Сортує отримані ID в алфавітному порядку.
+7. Повертає відсортований список ID правил.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).

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

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

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

@@ -0,0 +1,32 @@
+---
+type: JS Module
+title: mirror-parity.mjs
+resource: npm/scripts/lib/mirror-parity.mjs
+docgen:
+  crc: 91a0c9f2
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 90
+---
+
+Модуль реалізує механізм перевірки паралельності (parity) дзеркал правил. Він визначає список дзеркал, створює очікуваний вміст для кожного дзеркала, трансформуючи канонічний файл `npm/rules/<id>/<id>.mdc` з inlined-шаблонами — тим самим трансформом, що застосовує синк (`readBundledRuleContent` → `inlineTemplateLinks`). Механізм виявляє дрейф, коли фактичний вміст дзеркала `.cursor/rules/n-<id>.mdc` відрізняється від очікуваного, що виникає при зміні канонічного `.mdc` без регенерації дзеркала.
+
+## Поведінка
+
+listManagedMirrors
+Визначає список керованих дзеркал правил, які мають канонічне джерело в `npm/rules`.
+
+expectedMirrorContent
+Створює очікуваний вміст дзеркала, трансформуючи канонічний файл з вбудованими шаблонами.
+
+findMirrorDrift
+Виявляє ідентифікатори дзеркал, чий фактичний вміст відрізняється від очікуваного вмісту, отриманого з канону.
+
+## Публічний API
+
+listManagedMirrors — перераховує лише ті дзеркала, які мають визначене основне джерело (канон).
+expectedMirrorContent — визначає, як має виглядати вміст дзеркала, використовуючи канонічну версію з вбудованими шаблонами.
+findMirrorDrift — виявляє ідентифікатори дзеркал, чий фактичний вміст відрізняється від очікуваного.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).