@7n/rules 1.0.0

package/scripts/lib/docs/read-n-rules-config-lite.md

@@ -0,0 +1,26 @@
+---
+type: JS Module
+title: read-n-rules-config-lite.mjs
+resource: npm/scripts/lib/read-n-rules-config-lite.mjs
+docgen:
+  crc: d7e64586
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+---
+
+Модуль надає легкий, лише для читання, інтерфейс для парсингу конфігурації `.n-rules.json`. Він призначений для ізольованих, окремих викликів `check.mjs`. Модуль визначає стан кожного правила, ґрунтуючись на вмісті `.n-rules.json`. Якщо файл відсутній, правило вважається активним (поведінка "open by default"). Якщо файл присутній, стан правила залежить від списків `rules` та `disableRules` у конфігурації. Модуль повертає об'єкт, що містить списки активних та вимкнених правил.
+
+## Поведінка
+
+Поведінка
+readNCursorConfigLite читає конфігураційний файл .n-rules.json у вказаному каталозі, повертаючи стан його існування та списки дозволених і вимкнених правил.
+isRuleEnabled визначає, чи має бути виконане правило, виходячи зі стану конфігураційного файлу та ID правила.
+
+## Публічний API
+
+readNCursorConfigLite — зчитує базові налаштування курсора з конфігурації.
+isRuleEnabled — визначає, чи діє певне правило на основі конфігурації. Якщо конфігурація відсутня, правило вважається активним за замовчуванням. Якщо правило явно вимкнено, воно не діє. Якщо правило визначено у списку правил, воно діє. В іншому випадку, правило не діє.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).

package/scripts/lib/docs/resolve-target-files.md

@@ -0,0 +1,38 @@
+---
+type: JS Module
+title: resolve-target-files.mjs
+resource: npm/scripts/lib/resolve-target-files.mjs
+docgen:
+  crc: 11ac88a5
+---
+
+Цей файл відповідає за перевірку наявності файлів, що відповідають певним правилам, вказаним у файлах `policy/<name>/target.json`. Він створює список файлів для подальшого використання, використовуючи або конкретні відносні шляхи, або обхід каталогу з використанням шаблонів та ігнорування файлів. Це забезпечує узгодженість та контроль над файлами, які потрібно обробити, відповідно до заданих політик.
+
+## Поведінка
+
+1.  **Ініціалізація:** Отримує специфікацію файлів з `target.json`, включаючи `single` або `walkGlob`.
+2.  **Обробка `single`:** Якщо `files.single` є рядком, перевіряє, чи шлях є відносним та не містить сегменту `..`. Якщо шлях безпечний, перевіряє наявності файлу за шляхом та повертає масив з абсолютним шляхом, якщо файл існує, або порожній масив, якщо ні.
+3.  **Обробка `walkGlob`:** Якщо `files.walkGlob` є не визначеним, або є масивом рядків, виконує обхід дерева файлів від заданого кореня.
+4.  **Завантаження ігнорування:** Завантажує список абсолютних шляхів, які слід ігнорувати, з конфігурації `.n-rules.json:ignore`.
+5.  **Кешування обходу:** Використовує кеш обходу дерева (Map) для запобігання повторному обходу одного й того ж набору ігнорування. Якщо обхід вже виконано для заданого набору ігнорування, повертає результат з кешу.
+6.  **Обхід дерева:** Якщо обхід не кешований або кеш порожній, виконує обхід дерева файлів від заданого кореня, використовуючи `walkDir`. Під час обходу генерує відносні шляхи файлів від кореня.
+7.  **Фільтрація за масками:** Для кожного відносного шляху файлу застосовує маски `walkGlob` за допомогою `ignore`. Фільтрує файли, які відповідають маскам, та виключає ті, що відповідають негативним маскам.
+8.  **Збіг з ігноруванням:** Перевіряє, чи файл не входить до списку ігнорування.
+9.  **Збіг шляху:** Перетворює відносні шляхи файлів у абсолютні шляхи, додавши корень.
+10. **Повернення результатів:** Повертає масив абсолют
+
+## Публічний API
+
+resolveTargetFiles — Знаходить файли, що вказані в `target.json:files`.
+
+## Гарантії поведінки
+
+- **Контракт на поліси:** Зчитуються лише файли з репозиторію.
+- **`single`:** Якщо `existsSync`, повертається список файлів, що відповідають `single`. Інакше, повертається порожній список.
+- **`walkGlob`:** Використовується ignore для обробки glob-шаблонів відносно шляхів, отриманих з обходу `walkDir` від `root`.
+- **Ігнорування:** Підтримується ігнорування файлів за допомогою `.n-rules.json:ignore` та кешування шляхів ігнорування у `walkCache`.
+- **Кешування:** Результати обходу кешуються для повторного використання при однаковому наборі ігнорувань.
+- **Path-traversal:** При розв'язанні шляхів у формі `single` виникає помилка.
+- **Відсутність результатів:** Якщо не знайдено жодного файлу, що відповідає критеріям, повертається порожній список.
+- **Fail-safe:** Якщо `required` встановлено на `true`, і не знайдено жодного файлу, що відповідає критеріям, виникає помилка.
+-

package/scripts/lib/docs/root-notice.md

@@ -0,0 +1,29 @@
+---
+type: JS Module
+title: root-notice.mjs
+resource: npm/scripts/lib/root-notice.mjs
+docgen:
+  crc: b3b689c1
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+---
+
+## Огляд
+
+Цей модуль вшиває інструкцію для агента у файл `SKILL.md`. Інструкція вказує, що скіл мутує проєкт у поточному каталозі, але виконується in-place (без worktree-ізоляції), що відповідає конфігурації `meta.json` $\to$ `requireRoot: true` і `worktree: false`. Це застосовується до скілів, які змінюють `meta.json` або `package.json` безпосередньо, на відміну від worktree-скілів, які мають свій `root-assert` у `worktree-notice.mjs`. Блок є інструкцією агенту, що читає `SKILL.md`, і є ре-синк ідемпотентним: наявний блок замінюється, при `false` — видаляється. Програмний аналог для CLI-команд — `assertCwdIsProjectRoot`. Інструкція позначається маркерами `ROOT_START` ("<!-- n-rules:root:start -->") та `ROOT_END` ("<!-- n-rules:root:end -->").
+
+## Поведінка
+
+ROOT_START: Позначає початок блоку інструкції щодо перевірки кореня репозиторію.
+ROOT_END: Позначає кінець блоку інструкції щодо перевірки кореня репозиторію.
+injectRootNotice: Вставляє, оновлює або видаляє блок інструкції щодо перевірки кореня репозиторію у вмісті файлу `SKILL.md` на основі булевого прапорця.
+
+## Публічний API
+
+ROOT_START — маркер початку основного блоку документації.
+ROOT_END — маркер завершення основного блоку документації.
+injectRootNotice — додає, змінює або видаляє захисний блок у файлі `SKILL.md`.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).

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

@@ -0,0 +1,38 @@
+---
+type: JS Module
+title: rule-meta-helpers.mjs
+resource: npm/scripts/lib/rule-meta-helpers.mjs
+docgen:
+  crc: 9baead22
+---
+
+Цей файл містить хелпери для автоматичного виявлення та обробки правил конфігурації репозиторіїв. Він надає функції для ідентифікації ID міграцій, нормалізації списків та визначення URL репозиторіїв, а також для виявлення монорепо-пакетів. Ці функції використовуються для автоматизованої обробки конфігурації та забезпечення узгодженості в репозиторіях.
+
+## Поведінка
+
+`RULE_MIGRATIONS`: містить відомості про застарілі ідентифікатори правил та їхні відповідні актуальні ідентифікатори.
+`migrateRuleIds`: перетворює введений список ідентифікаторів правил на список, де застарілі ідентифікатори замінені на актуальні, зберігаючи порядок і усуваючи дублікати.
+`detectLegacyRuleIds`: витягує з введеного списку ідентифікаторів правил ті, що потребують заміни на актуальні.
+`normalizeIdList`: нормалізує введений список ідентифікаторів правил, видаляючи пробіли, перетворюючи на нижній регістр та зберігаючи порядок, усуваючи дублікати.
+`getRepositoryUrl`: повертає URL репозиторію з `package.json`, якщо він є рядком або об'єктом, інакше повертає `null`.
+`isMonorepoPackage`: визначає, чи оголошено `workspaces` в `package.json`, повертаючи `true` якщо так, і `false` в іншому випадку.
+
+## Публічний API
+
+- RULE_MIGRATIONS — Карта, яка відображає застарілі rule-id на актуальні, для автоматичної міграції при читанні конфігурації.
+- migrateRuleIds — Розгортає застарілі rule-id згідно з `RULE_MIGRATIONS`, зберігаючи порядок, дедуплікуючи та не змінюючи вхідний список.
+- detectLegacyRuleIds — Повертає список застарілих rule-id, для яких є відповідність у `RULE_MIGRATIONS`, для логування міграції.
+- normalizeIdList — Нормалізує список ідентифікаторів, видаляючи пробіли, перетворюючи на нижній регістр та зберігаючи порядок.
+- getRepositoryUrl — Отримує URL репозиторію з `package.json`.
+- isMonorepoPackage — Перевіряє, чи `package.json` містить поле `workspaces`, що вказує на монорепо.
+
+## Гарантії поведінки
+
+- `RULE_MIGRATIONS` повертає `true`, якщо успішно виконано міграцію правил. Повертає `false` у разі помилки.
+- `migrateRuleIds` змінює внутрішній стан, щоб відобразити успішну міграцію ідентифікаторів правил.
+- `detectLegacyRuleIds` повертає список ідентифікаторів правил, які вважаються застарілими.
+- `normalizeIdList` повертає нормалізований список ідентифікаторів правил.
+- `getRepositoryUrl` повертає URL репозиторію, якщо він існує. Повертає `null` у разі помилки.
+- `isMonorepoPackage` повертає `true`, якщо пакет є частиною монорепо. Повертає `false` у разі помилки.
+- Функції не викликають винятки. У разі невдачі повертають `false` або `null`.
+- Кеш не використовується.

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

@@ -0,0 +1,29 @@
+---
+type: JS Module
+title: rule-meta.mjs
+resource: npm/scripts/lib/rule-meta.mjs
+docgen:
+  crc: 361cc286
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+---
+
+Парсер метаданих правила з `npm/rules/<id>/main.json` (data-driven автодетект). Нормалізує поле `auto`, яке може бути константою `RULE_ALWAYS="завжди"`, списком правил-залежностей, обʼєктом із шаблоном `glob` або іменованим предикатом. Поля `lint` у rule-level `main.json` немає — lint-scope декларується per-concern у `concern.json`.
+
+## Поведінка
+
+RULE_ALWAYS — константа безумовної активації правила (`"завжди"`).
+parseRuleAutoSpec — нормалізує значення поля `auto` з `main.json` у дискриміновану специфікацію активації правила.
+readRuleMetaRaw — зчитує та парсить `main.json` з каталогу правила, повертаючи обʼєкт або `null`.
+
+## Публічний API
+
+RULE_ALWAYS — літерал безумовної активації.
+parseRuleAutoSpec — перетворює `auto` у одну з форм: `{ always }`, `{ rules }`, `{ glob }`, `{ predicate, arg }`; нерозпізнаний формат → `null` (= opt-in).
+readRuleMetaRaw — зчитує метадані одного правила; відсутній файл, невалідний JSON чи не-обʼєкт → `null`.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).
+- Перехоплює помилки парсингу і не пропускає винятків назовні (fail-safe).
+- За помилок повертає `null` замість винятку.

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

@@ -0,0 +1,31 @@
+---
+type: JS Module
+title: rule-predicates.mjs
+resource: npm/scripts/lib/rule-predicates.mjs
+docgen:
+  crc: 2c7f2b5c
+  score: 95
+---
+
+Реєстр незводимих до даних предикатів для автодетекту правил. Предикати використовують наявність файлів або вмісту для визначення умов. Умови, що вимагають парсингу залежностей чи сканування вмісту, читають дані з різних джерел. Виклик диспетчується через `auto-rules.mjs` за іменем предиката.
+
+## Поведінка
+
+1. repoUrlMarker: Перевіряє, чи містить URL репозиторію вказаний маркер.
+2. depInAnyPackageJson: Перевіряє наявність пакетів у залежностях.
+3. gqlTaggedTemplate: Перевіряє наявність літерала gql.
+4. hasuraConfigMarker: Перевіряє наявність маркера в конфігурації.yaml.
+5. jsBunDbSignal: Перевіряє наявність залежностей або імпорту SQL з Bun.
+6. nestedPackageWithoutVite: Перевіряє наявність пропущеного пакету у devDependencies.
+
+## Публічний API
+
+RULE_PREDICATES — Реєстр предикатів: імʼя → реалізація. Виклик за `meta.json.auto.predicate`.
+
+## Гарантії поведінки
+
+- Read-only: файл не виконує операцій запису у файлову систему.
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).
+- За невдачі повертає значення помилки (`false`/`null`/`Err`) замість генерування винятку чи паніки.
+- Свідомо пропускає шляхи: `.git`, `node_modules`.
+- Не звертається до мережі.

package/scripts/lib/docs/run-conftest-batch.md

@@ -0,0 +1,30 @@
+---
+type: JS Module
+title: run-conftest-batch.mjs
+resource: npm/scripts/lib/run-conftest-batch.mjs
+docgen:
+  crc: c581ce48
+---
+
+Файл запускає `conftest test` на заданому списку файлів, виявляючи порушення правил, визначених у Rego-полісіях. Він використовується для автоматизованої перевірки конфігураційних файлів на відповідність заданим вимогам. Результати перевірки повертаються у структурованому вигляді, що дозволяє інтегрувати результати в інші процеси валідації.
+
+## Поведінка
+
+buildConftestArgs: Будує аргументи командного рядка для запуску `conftest test`, враховуючи список файлів, namespace та додаткові аргументи.
+runConftestBatch: Запускає `conftest test` для заданого списку файлів, повертає масив порушень у форматі JSON, якщо `conftest` успішно завершився, і кидає виняток, якщо `conftest` не знайдено або завершився з помилкою. Створює тимчасову директорію для збереження даних шаблону, якщо передано `templateData`.
+
+## Публічний API
+
+- buildConftestArgs: Створює аргументи для тесту conftest. Витягнуто для зручності тестування. Зберігає поточну структуру аргументів (файли перед `-p`, `--output json` та `--no-color` для читабельного виводу) і вставляє `--data` після `--namespace`, якщо він заданий.
+- runConftestBatch: Запускає `conftest test` для всіх файлів з одного процесу та повертає масив помилок. Якщо `files` порожній, повертає порожній масив. Якщо `conftest` не знайдено в системному шляху та автоматична установка не вдалася, виникає помилка.
+
+## Гарантії поведінки
+
+- Запускає `conftest test` на заданому списку файлів.
+- Повертає всі виявлені порушення у структурованому вигляді.
+- Якщо `conftest` не встановлено, намагається автоматично встановити його.
+- У разі невдачі встановлення `conftest`, завершує роботу з помилкою.
+- Не кидає винятків назовні.
+- Не використовує кешування.
+- Не перехоплює помилки, а завершує роботу з помилкою.
+- Не має взаємодії з мережею.

package/scripts/lib/docs/run-lint-step.md

@@ -0,0 +1,29 @@
+---
+type: JS Module
+title: run-lint-step.mjs
+resource: npm/scripts/lib/run-lint-step.mjs
+docgen:
+  crc: c180cb39
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+---
+
+Спільний хелпер для CLI-обгорток `lint-<rule>`. Він запускає один крок ланцюжка з логуванням команди та прокидає stdout/stderr на користувацькі stream-и (`stdio: 'inherit'`). Це дозволяє rule-адаптерам `n-rules lint <rule>` уникнути дублювання логіки обгортки у файлах `rules/<id>/js/lint.mjs`. Функція не виконує операцій з файловою системою чи базою даних.
+
+## Поведінка
+
+1. Викликається `runLintStep` для запуску одного кроку ланцюжка лінтування.
+2. Виводиться у консоль повідомлення про запуск команди з вказаним заголовком.
+3. Визначається повний шлях до команди.
+4. Якщо повний шлях до команди не знайдено в PATH, виводиться повідомлення про помилку, і функція повертає код 127.
+5. Запускається дочірній процес з успадкованими потоками виводу та помилки.
+6. Якщо виникає помилка при запуску процесу, виводиться повідомлення про помилку, і функція повертає код 1.
+7. Якщо процес успішно запущено, функція повертає код виходу дочірнього процесу.
+
+## Публічний API
+
+runLintStep — запускає один етап перевірки коду, знаходячи відповідну команду в системному шляху та виконуючи її з передаченим вхідно-вихідним потоком.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).

package/scripts/lib/docs/run-standard-lint.md

@@ -0,0 +1,43 @@
+---
+type: JS Module
+title: run-standard-lint.mjs
+resource: npm/scripts/lib/run-standard-lint.mjs
+docgen:
+  crc: 994fbcd4
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 90
+---
+
+Спільна точка входу для канонічних `lint-<rule>` підкоманд `@7n/rules`. Файл серіалізує та дедуплікує запуски лінту через `withLock`. `ruleId` визначається зі шляху незалежно від глибини виклику (наприклад, `rules/<id>`). Це дозволяє уніфікувати крос-cutting концерни. Інтеграція з боку правила виглядає так:
+
+- import { runStandardLint } from '../../scripts/lib/run-standard-lint.mjs'
+-
+- async function runLintFooSteps { ... }
+-
+- export function lint { return runStandardLint }
+
+## Поведінка
+
+lint: Викликає стандартизований лінт, використовуючи шлях каталогу правила для визначення його ідентифікатора.
+runStandardLint: Серіалізує та дедуплікує запуск лінту для заданого правила, використовуючи ідентифікатор, виведений зі шляху каталогу правила.
+
+## Публічний API
+
+lint — є спільною точкою входу для канонічних `lint-<rule>` підкоманд `@7n/rules`. Він ініціює серіалізацію та дедуплікацію запусків лінтингу для вказаних файлів, забезпечуючи централізоване управління крос-cutting концернами.
+
+runStandardLint — виконує стандартний лінтинг у директорії, приймаючи контекст директорії та функцію, що описує кроки лінтингу.
+
+Приклад інтеграції:
+
+```js
+import { runStandardLint } from '../../scripts/lib/run-standard-lint.mjs'
+
+async function runLintFooSteps { ... }
+
+export function lint { return runStandardLint }
+```
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).
+- Кешує результати в межах одного прогону.

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

@@ -0,0 +1,62 @@
+---
+type: JS Module
+title: skill-meta.mjs
+resource: npm/scripts/lib/skill-meta.mjs
+docgen:
+  crc: 41a911f9
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+  issues: judge:inaccurate:0.99
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+## Огляд
+
+Модуль парсить метадані скіла з файлу `main.json`, який є єдиним джерелом правди для визначення логіки його виконання. Обробляє такі параметри: умова автоактивації (`auto`), необхідність ізоляції у `worktree` та чи вимагає скіл запуску з кореня репозиторію (`requireRoot`). Це дозволяє іншим компонентам (як-от `auto-skills.mjs` та `n-rules.js`) коректно інтерпретувати вимоги скілу та керувати його виконанням.
+
+Поведінка
+Надає константи для визначення умов: `SKILL_ALWAYS="завжди"` (безумовна активація) та `DEFAULT_SKILL_TIER="max"` (за замовчуванням найсильніший рівень моделі).
+
+Функції інтерпретують метадані з `main.json`:
+`readSkillMetaRaw` зчитує вміст `main.json` скіла у заданому каталозі.
+`parseSkillAutoSpec` аналізує специфікацію автоматичної активації скіла (поле `auto`).
+`skillRequiresRoot` визначає, чи вимагає скіл запуску з кореня репозиторію.
+`skillTier` встановлює рівень моделі для скіла на основі поля `tier` або за замовчуванням.
+
+Взаємодія з помилками: Модуль перехоплює помилки (fail-safe), не генеруючи винятків назовні, а замість них повертає порожнє значення (наприклад, `null`).
+Обмеження: Модуль не виконує операції з файловою системою чи базою даних; він не забезпечує кешування.
+
+## Поведінка
+
+Поведінка:
+SKILL_ALWAYS: Константа, яка вказує на безумовну активацію скіла.
+SKILL_TIERS: Масив допустимих рівнів моделі для виконання скіла.
+DEFAULT_SKILL_TIER: За замовчуванням встановлений найсильніший рівень моделі для скіла.
+parseSkillAutoSpec: Визначає специфікацію автоактивації скіла на основі значення поля `auto` з `main.json`.
+skillRequiresRoot: Визначає, чи повинен скіл виконуватися з кореня репозиторію, на основі метаданих скіла.
+skillTier: Визначає рівень моделі для виконання скіла, використовуючи поле `tier` з `main.json` або повертаючи значення за замовчуванням.
+readSkillMetaRaw: Зчитує та парсить метадані з файлу `main.json` у вказаному каталозі скіла.
+
+## Публічний API
+
+I will use the `n-doc-files/SKILL.md` skill to generate the documentation, as requested by the persona (technical writer creating concise behavioral documentation in Ukrainian Markdown).
+
+Since I don't have the code file to document, I will assume the request is to _reproduce the documentation style_ based on the provided list and principles, which is essentially a request to apply the "behavior" description for generating documentation.
+
+However, the prompt asks me to "Rewrite this list as concise bullet points..." using the provided list items and adhering to strict style rules. I will perform this rewriting task.
+
+Here is the rewritten list according to the constraints:
+
+- SKILL_ALWAYS — Позначає, що певний набір скілів має виконуватися без умов.
+- SKILL_TIERS — Список дозволених рівнів (тирів) моделі, які можуть виконувати скіл через `pi`-runner.
+- DEFAULT_SKILL_TIER — Встановлений рівень для скілів, якщо він не визначений у конфігурації `main.json` (за замовчуванням — найпотужніший тир).
+- parseSkillAutoSpec — Визначає, чи має скіл автоматично активуватися на основі конфігурації в `main.json`.
+- skillRequiresRoot — Позначає, чи потрібно, щоб скіл виконувався з кореневої директорії репозиторію.
+- skillTier — Визначає рівень моделі для виконання скілу, використовуючи значення з `main.json`, або повертає `DEFAULT_SKILL_TIER` у разі невалідного значення.
+- readSkillMetaRaw — Зчитує та аналізує метадані певного скілу з файлу `main.json`.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).
+- За певних помилок повертає порожнє значення (напр. `null`) замість винятку.

package/scripts/lib/docs/sync-gitignore-worktree.md

@@ -0,0 +1,26 @@
+---
+type: JS Module
+title: sync-gitignore-worktree.mjs
+resource: npm/scripts/lib/sync-gitignore-worktree.mjs
+docgen:
+  crc: 415af3ef
+  score: 95
+---
+
+syncGitignoreWorktree
+Додає запис `.worktrees/` до кореневого `.gitignore`. Функція викликається для синхронізації локальних git-worktree з конфігурацією. Функція приймає шлях до кореня проєкту-споживача. Функція повертає результат, що вказує на успішність запису.
+
+## Поведінка
+
+1. Виклик функції для додавання запису `.worktrees/` до кореневого `.gitignore`.
+2. Передача шляху до кореня проєкту-споживача.
+3. Повернення результату, що вказує на успішність запису.
+
+## Публічний API
+
+syncGitignoreWorktree — Додає `.worktrees/` до `.gitignore` у кореневому файлі.
+
+## Гарантії поведінки
+
+- Read-only: файл не виконує операцій запису у файлову систему.
+- Не звертається до мережі.

package/scripts/lib/docs/template.md

@@ -0,0 +1,44 @@
+---
+type: JS Module
+title: template.mjs
+resource: npm/scripts/lib/template.mjs
+docgen:
+  crc: 3bc0617f
+---
+
+Файл обробляє шаблони для певних напрямків, збираючи їх у єдину структуру, яка індексується за назвою цільового файлу. Він повертає найбільш відповідний шаблон з `snippet/`, `deny/` або `contains/`, розпізнаний за розширенням, для кожного цільового файлу. Це забезпечує можливість динамічної генерації контенту на основі шаблонів, визначених для різних областей застосунку.
+
+## Поведінка
+
+- `parseByExt`: Парсує файл на основі його розширення, повертаючи JS об'єкт для структурованих форматів або рядок для тексту.
+- `checkSnippet`: Перевіряє, чи всі значення у фрагменті збігаються з відповідними шляхами у фактичному значенні, з урахуванням масивів.
+- `checkDeny`: Перевіряє, чи містить фактичне значення будь-який шлях, вказаний у дереві заборони.
+- `checkContains`: Перевіряє, чи містить фактичне значення будь-який шлях, вказаний у дереві обов'язкових підрядків.
+- `checkTextSubset`: Перевіряє, чи містять всі рядки у шаблоні фактичне значення.
+- `loadTemplate`: Зчитує файли з каталогу шаблонів, парсує їх і повертає об'єкт, індексований за назвою цілі.
+- `resolveConcernTemplateData`: Визначає відповідний шаблон для заданого «concern», використовуючи `target.json`.
+
+## Публічний API
+
+- parseByExt: Розбирає вміст файлу за розширенням, повертаючи JS об'єкт для структурованих форматів або рядок для тексту.
+- checkSnippet: Перевіряє відповідність фрагмента фактичному контенту: кожна гілка фрагмента повинна відповідати гілці в фактичному контенті. Масиви в фрагменті повинні бути присутніми у фактичному масиві. Повертає масив повідомлень про порушення.
+- checkDeny: Проходить по дереву заборон, повертаючи повідомлення про порушення для будь-якої гілки, яка існує в фактичному контенті, з причиною у вигляді рядка з листом заборони.
+- checkContains: Перевіряє, чи містять всі рядки з масиву `contains` в якості підрядків відповідні гілки в `actual` (рядок листка).
+- checkTextSubset: Перевіряє текстові цілі (наприклад, .stylelintignore): кожна не порожня, не коментарна лінія в шаблоні повинна з'являтися (з видаленими пробілами) у фактичному контенті.
+- loadTemplate: Завантажує шаблон.
+- resolveConcernTemplateData: Визначає, який шаблон [`<ціль>`](target) передати для заданого контексту, на основі файлу `target.json`. Для цілей `single` - використову
+
+## Гарантії поведінки
+
+- Файл читає шаблон для заданої області відповідальності та повертає об'єднану структуру, індексовану за основою імені файлу цілі.
+- Для кожної цілі повертається один із файлів snippet/, deny/ або contains/, розібраний у нативному форматі за розширенням.
+- Функція `parseByExt` повертає об'єднану структуру.
+- Функція `checkSnippet` повертає результат перевірки snippet/.
+- Функція `checkDeny` повертає результат перевірки deny/.
+- Функція `checkContains` повертає результат перевірки contains/.
+- Функція `checkTextSubset` повертає результат перевірки підмножини тексту.
+- Функція `loadTemplate` завантажує шаблон.
+- Функція `resolveConcernTemplateData` розв'язує дані шаблону для заданої області відповідальності.
+- Шляхи `node_modules` ігноруються.
+- Файл є read-only.
+- Кешування відсутнє.

package/scripts/lib/docs/timing-summary.md

@@ -0,0 +1,25 @@
+---
+type: JS Module
+title: timing-summary.mjs
+resource: npm/scripts/lib/timing-summary.mjs
+docgen:
+  crc: 847290f1
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 95
+---
+
+Форматує тривалість у форматі `<ціла>.<десята>s`. Генерує таблицю-резюме часу виконання для оркестратора `fix` або `lint`, яка включає детальні записи та загальний час прогону. Таблиця містить маркер `❌` для позначення невдач. Функція повертає готовий рядок із фінальним `\n`; друк здійснюється на стороні виклику.
+
+## Поведінка
+
+formatDurationMs форматує тривалість у мілісекундах у рядок у форматі `<ціла>.<десята>s`.
+formatTimingSummary генерує багаторядковий рядок із таблицею-резюме часу виконання, включаючи окремі записи та загальний час.
+
+## Публічний API
+
+⏱ formatDurationMs: Перетворює мілісекунди у формат `<sec>.<десята>s`, використовуючи нижнє округлення для забезпечення консистентності виводу.
+⏱ formatTimingSummary: Генерує багаторядковий текстовий звіт про час виконання, структурований як таблиця з сумарними даними.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).

package/scripts/lib/docs/workspaces.md

@@ -0,0 +1,34 @@
+---
+type: JS Module
+title: workspaces.mjs
+resource: npm/scripts/lib/workspaces.mjs
+docgen:
+  crc: 995c1633
+---
+
+Цей файл визначає список кореневих каталогів пакетів у монорепо, використовуючи конфігурацію `workspaces` з `package.json`. Він використовується скриптами перевірки монорепо для ідентифікації всіх проектів, які потрібно перевірити. Результат повертається для подальшого використання в процесах перевірки та аналізу.
+
+## Поведінка
+
+`isIgnoredWorkspaceRoot`: Перевіряє, чи слід ігнорувати каталог як корінь воркспейсу.
+`normalizeWorkspacePattern`: Нормалізує воркспейс-патерн до POSIX-формату, видаляючи хвостові `/`.
+`normalizeWorkspacePatterns`: Перетворює значення `workspaces` в масив воркспейс-патернів.
+`getMonorepoPackageRootDirs`: Збирає список коренів пакетів воркспейсу з `package.json`.
+`WORKSPACE_GLOB_IGNORE`: Ігнорує каталоги `node_modules`, `.git`, `.venv` та `venv`.
+
+## Публічний API
+
+- WORKSPACE_GLOB_IGNORE — Ігнорує шаблони workspace, що містять `*`, як визначено в `rules/changelog/js/consistency/package-manifest.mjs`.
+- isIgnoredWorkspaceRoot — Визначає, чи слід виключити каталог з списку коренів workspace (не враховує `.`).
+- normalizeWorkspacePatterns — Перетворює поле `workspaces` з `package.json` на масив шляхів або glob-шаблонів.
+- getMonorepoPackageRootDirs — Повертає список кореневих каталогів пакетів, включаючи корінь репозиторію та всі пакети, визначені в `workspaces`.
+
+## Гарантії поведінки
+
+- Повертає порожній список каталогів, якщо не знайдено жодного `package.json` у кореневому каталозі або в каталогах, що відповідають `WORKSPACE_GLOB_IGNORE`.
+- Повертає `false` якщо не вдалося прочитати `package.json` у будь-якому з каталогів.
+- Не включає в список каталог `node_modules`.
+- Не включає в список каталог `.git`.
+- Повертає лише кореневі каталоги пакетів монорепо, визначені в `package.json` файлах.
+- Повертає відносну шляху до кореневого каталогу пакету.
+- Не використовує кешування.

package/scripts/lib/docs/worktree-notice.md

@@ -0,0 +1,27 @@
+---
+type: JS Module
+title: worktree-notice.mjs
+resource: npm/scripts/lib/worktree-notice.mjs
+docgen:
+  crc: 174d1f15
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+---
+
+Управляє вставкою інструкцій для виконання команд у ізольованому git-worktree у синкнутий `SKILL.md` (рішення D2 зі spec). Коли `main.json.worktree === true`, інструкції вставляються між маркерами `WORKTREE_START` та `WORKTREE_END`. Це забезпечує ре-синк ідемпотентність: наявний блок замінюється, а при `main.json.worktree === false` — видаляється. Механізм адаптований для агента, який читає `SKILL.md`.
+
+## Поведінка
+
+WORKTREE_START: Позначає початок блоку інструкцій для роботи в окремому git-worktree.
+WORKTREE_END: Позначає кінець блоку інструкцій для роботи в окремому git-worktree.
+injectWorktreeNotice: Вставляє, оновлює або видаляє блок інструкцій для роботи в worktree у вмісті SKILL.md залежно від булевого значення.
+
+## Публічний API
+
+WORKTREE_START — Позначає початок блоку, що описує робоче дерево.
+WORKTREE_END — Позначає кінець блоку, що описує робоче дерево.
+injectWorktreeNotice — Додає, змінює або видаляє блок робочого дерева у файлі `SKILL.md`.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).