@nitra/cursor 3.27.0 → 3.29.0

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

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

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

@@ -0,0 +1,28 @@
+# root-notice.mjs
+
+## Огляд
+
+Цей файл вставляє root-guard preflight для скілів, які змінюють проєкт у поточному каталозі. Він забезпечує, що скіл виконується in-place, без ізоляції worktree, і використовується для випадків, коли не потрібна ізоляція worktree. Це гарантує коректне виконання скілу від імені проєкту.
+
+## Поведінка
+
+ROOT_START: вставляє маркер початку root-блоку.
+ROOT_END: вставляє маркер кінця root-блоку.
+injectRootNotice: вставляє, оновлює або видаляє root-guard блок у вмісті `SKILL.md` на основі параметра `enabled`.
+
+## Публічний API
+
+- ROOT_START — Позначає початок блоку root.
+- ROOT_END — Позначає кінець блоку root.
+- injectRootNotice — Змінює вміст `SKILL.md` щодо root-guard блоку.
+
+## Гарантії поведінки
+
+- Якщо `requireRoot: true` у `meta.json`, то поточний робочий каталог є коренем проєкту.
+- Якщо `requireRoot: false`, то блок не вставляється.
+- Вставка відбувається лише між маркерами.
+- Вставка ре-синк ідемпотентно: наявний блок замінюється.
+- `ROOT_START` викликається перед вставкою блоку.
+- `ROOT_END` викликається після вставки блоку.
+- `injectRootNotice` викликається під час вставки блоку.
+- Немає кешування.

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

@@ -0,0 +1,34 @@
+# rule-meta-helpers.mjs
+
+## Огляд
+
+Цей файл містить хелпери для автоматичного виявлення та обробки правил конфігурації репозиторіїв. Він надає функції для ідентифікації 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,34 @@
+# rule-meta.mjs
+
+## Огляд
+
+Цей файл парсує метадані правил npm/rules/<id>/meta.json для автоматичного виявлення проблемних місць у коді. Він визначає, коли правило має бути активним, використовуючи різні специфікації, такі як завжди-ввімкнене правило, правило, яке активується після виявлення залежностей, або правило, яке активується на основі glob-шаблонів чи незводимих предикатів. Це дозволяє системі динамічно визначати та застосовувати правила, не потребуючи явного налаштування.
+
+## Поведінка
+
+`RULE_ALWAYS`: визначає літерал для активації правила "завжди".
+`parseRuleAutoSpec`: нормалізує значення `meta.json.auto` у дискриміновану форму.
+`parseRuleLintPhase`: нормалізує значення `meta.json.lint` у фазу lint.
+`readRuleMetaRaw`: читає та парсить `meta.json` одного правила, повертаючи об’єкт або `null`.
+
+## Публічний API
+
+- RULE_ALWAYS — Активує правило.
+- parseRuleAutoSpec — Перетворює значення `meta.json.auto` на конкретну опцію.
+- parseRuleLintPhase — Перетворює значення `meta.json.lint` на фазу lint.
+- readRuleMetaRaw — Зчитує та аналізує файл `meta.json` правила.
+
+## Гарантії поведінки
+
+- `RULE_ALWAYS` повертає `true` якщо правило активне.
+- `parseRuleAutoSpec` повертає `true` якщо специфікація правила успішно розібрана.
+- `parseRuleAutoSpec` повертає `false` якщо специфікація правила не може бути розібрана.
+- `parseRuleLintPhase` повертає `true` якщо правило успішно розібрано на етапі linting.
+- `parseRuleLintPhase` повертає `false` якщо правило не може бути розібрано на етапі linting.
+- `readRuleMetaRaw` повертає `true` якщо метадані правила успішно прочитані.
+- `readRuleMetaRaw` повертає `false` якщо метадані правила не можуть бути прочитані.
+- У разі невдачі, функція повертає `false` або `null`.
+- Функції не кидають винятків.
+- Немає кешування.
+- Немає гарантій щодо стану файлів або каталогів.
+- Поля `worktree` правила не використовуються.

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

@@ -0,0 +1,30 @@
+# rule-predicates.mjs
+
+## Огляд
+
+Цей файл містить набір предикатів, які використовуються для автоматичного визначення правил. Ці предикати дозволяють перевіряти наявність файлів, вміст source-коду та інформацію з репозиторіїв, щоб виявляти потенційні порушення правил. Він забезпечує механізм для автоматизованого пошуку та виявлення правил на основі даних.
+
+## Поведінка
+
+1.  **Ініціалізація перевірки репозиторію:** Отримує URL репозиторію з кореневого `package.json` або з `meta.json.repository`. Перевіряє, чи URL існує і чи містить він вказаний маркер.
+2.  **Перевірка залежностей у дереві:** Для кожного `package.json` у дереві репозиторію, перебирає всі пакети в залежностях. Якщо пакет має вказаний маркер, повертає `true`. Ігнорує директорії `node_modules`, `.git`, `.next` та `.turbo`.
+3.  **Перевірка вкладених `package.json`:** Для кореневого `package.json` перевіряє, чи є в будь-якому вкладеному `package.json` відсутній `vite` у секції `devDependencies`. Ігнорує директорії `node_modules`, `.git`, `.next` та `.turbo`.
+4.  **Перевірка фактів:** Якщо надано факти, перевіряє наявність `hasGqlTaggedTemplates` та `hasHasuraConfig`. Якщо `hasGqlTaggedTemplates` має значення `true`, повертає `true`. Якщо `hasHasuraConfig` має значення `true`, повертає `true`.
+5.  **Перевірка наявності `bun`:** Якщо надано факти, перевіряє наявність `hasBunSqlImport`. Якщо `hasBunSqlImport` має значення `true`, повертає `true`.
+6.  **Перевірка залежностей `pg`:** Якщо надано факти, перевіряє наявність `pg`, `pg-format` або `mysql2` у залежностях. Якщо будь-яка з цих залежностей присутня, повертає `true`.
+7.  **Перевірка вкладеного `package.json` без `vite`:** Отримує кореневий `package.json`. Перебирає всі вкладені `package.json` (крім кореневого). Якщо вкладений `package.json` не містить `vite` у `devDependencies`, повер
+
+## Публічний API
+
+RULE_PREDICATES — Зберігає предикати та їх реалізації. Використовується для виклику через `meta.json.auto.predicate`.
+
+## Гарантії поведінки
+
+- Функція повертає результат виконання предиката.
+- Результат може бути істинним або хибним.
+- При виникненні помилки, результат завжди хибний.
+- Не враховує наявність `.git` та `node_modules` у файловій системі.
+- Не використовує кешування.
+- Не генерує винятків.
+- Аргументи предиката можуть бути значеннями, отриманими з файлів `meta.json`, шляхів у файловій системі або URL-адрес.
+- Результат залежить від вмісту та структури зазначених джерел.

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

@@ -0,0 +1,26 @@
+# run-conftest-batch.mjs
+
+## Огляд
+
+Файл запускає `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,25 @@
+# run-lint-step.mjs
+
+## Огляд
+
+Цей файл забезпечує спільний хелпер для запуску окремих кроків у ланцюжку linting, що використовується CLI-обгортками. Він імітує прямий виклик команд у shell, логуючи команди та перенаправляючи stdout/stderr на користувацькі stream-и. Це дозволяє уникнути дублювання обгорток у різних `rules/<id>/js/lint.mjs` файлах.
+
+## Поведінка
+
+1.  Записує в лог повідомлення про початок виконання кроку ланцюжка з описом команди та її аргументів.
+2.  Визначає шлях до виконуваного файлу команди на основі її імені.
+3.  Якщо шлях не знайдено в системному PATH, записує повідомлення про помилку та повертає код 127.
+4.  Запускає визначену команду з заданими аргументами, передаючи стандартний потік введення/виведення (stdio) потокам користувача.
+5.  Якщо команда завершилася з помилкою, записує повідомлення про помилку та повертає код 1.
+6.  Якщо команда завершилася успішно, повертає код виходу дочірнього процесу, який дорівнює 0, якщо все добре, або 1, якщо виникла помилка.
+
+## Публічний API
+
+runLintStep — запускає процес linting та перевіряє його успішність.
+
+## Гарантії поведінки
+
+- Запускає один крок ланцюжка linting.
+- Перенаправляє stdout та stderr на користувацькі stream-и (stdio: 'inherit').
+- Не використовує кешування.
+- Не має внутрішніх приватних імен.

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

@@ -0,0 +1,27 @@
+# run-rule-cli.mjs
+
+## Огляд
+
+Цей файл є самостійним CLI-запускомком для правила, який дозволяє запускати правила з файлів `.n-cursor.json` та виконувати їхні дії. Він забезпечує інтеграцію з інструментом `cursor`, імітуючи старий `npx @nitra/cursor fix <id>`. Файл виконує перевірку whitelist, генерує summary та повертає агрегований код виходу.
+
+## Поведінка
+
+1.  Визначає ID правила на основі шляху директорії правила.
+2.  Зчитує конфігурацію з файлу `.n-cursor.json`.
+3.  Перевіряє, чи правило включено в конфігурації. Якщо ні, пропускає перевірку та повертає код успіху (0).
+4.  Виводить інформаційне повідомлення про початок перевірки правила.
+5.  Створює або отримує кеш для обходу файлової структури.
+6.  Запускає стандартний процес перевірки правила, передаючи кеш.
+7.  Отримує код завершення процесу перевірки правила.
+8.  Виводить підсумковий результат перевірки (успіх або невдача).
+9.  Повертає код завершення процесу перевірки правила.
+
+## Гарантії поведінки
+
+- Запускає правило з файлу `fix.mjs`.
+- Читає файл `.n-cursor.json` для конфігурації правила.
+- Перевіряє, чи правило включено в whitelist.
+- Виводить підсумкову інформацію про результат виконання.
+- Повертає код завершення, що відображає загальний статус виконання.
+- Кешує результати для уникнення повторного виконання, поки не змінено конфігурацію або не було перезапущено.
+- Не здійснює жодних мережевих запитів.

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

@@ -0,0 +1,32 @@
+# run-rule.mjs
+
+## Огляд
+
+Цей файл є оркестратором правил, що запускається з командного рядка. Він застосовує правила, визначаючи та виконуючи концерни, а також політичні концерни, використовуючи кешування для підвищення ефективності. Файл забезпечує централізований спосіб виконання правил та збору результатів.
+
+## Поведінка
+
+- `runTemplateSubsetConcern`: Перевіряє файл-концерт за допомогою шаблону, повертаючи 0, якщо все ОК, або 1, якщо є порушення.
+- `evaluateAppliesGate`: Викликає функцію `applies` з `js/applies.mjs`, якщо вона існує та повертає `true`.
+- `runPolicyConcern`: Запускає policy-концерт через `runConftestBatch`, повертаючи 0, якщо все ОК, або 1, якщо є порушення.
+- `runRule`: Оркеструє правила, викликаючи `evaluateAppliesGate`, JS-концерни та policy-концерни, об'єднуючи exit-коди.
+
+## Публічний API
+
+- runTemplateSubsetConcern — Перевірка відповідності шаблонів: порівнює конфігурацію шаблонів з фактичним файлом, забезпечуючи дотримання правил.
+- runRule — Запуск правила: виконує послідовність дій, включаючи перевірку концернів, і застосовує політику.
+
+## Гарантії поведінки
+
+- `applies-гейт` викликає `applies` з `js/applies.mjs`.
+- `applies` повертає `false` — виводить `✅ правило не застосовне` і завершує.
+- `JS-концерни` викликають `applies` після `applies-гейт`.
+- `JS-концерни` можуть викликати `check` для виведення контексту.
+- `Policy-концерни` викликають `runConftestBatch`.
+- `resolveTargetFiles` кешує результати `walkCache` між `JS-концернами`.
+- `createCheckReporter` у `Policy-концерни` OR-ює exit-коди.
+- Exit-код правила — 0 або 1.
+- `runTemplateSubsetConcern` запускає підмножину шаблонів.
+- `runRule` запускає правило.
+- Кеш використовується для зберігання результатів `resolveTargetFiles` у межах прогону.
+- Немає взаємодії з мережею.

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

@@ -0,0 +1,22 @@
+# run-standard-lint.mjs
+
+## Огляд
+
+Файл забезпечує централізовану точку запуску для підкоманд `lint-<rule>` у `@nitra/cursor`. Він серіалізує та дедублює запуски, використовуючи `withLock`, щоб гарантувати узгодженість та ефективність. Це дозволяє легко інтегрувати нові правила та обробляти крос-cutting концерни, не вносячи змін у окремі файли правил.
+
+## Поведінка
+
+runLintFooCli: Запускає лінт для правила, використовуючи `runStandardLint`.
+runStandardLint: Серіалізує та дедуплікує запуск лінту, використовуючи блокування. Визначає ідентифікатор правила з шляху.
+
+## Публічний API
+
+- runLintFooCli — Перевіряє код на відповідність стандартам Foo CLI.
+- runStandardLint — Перевіряє код на відповідність загальним стандартам кодування.
+
+## Гарантії поведінки
+
+- Приймає `ruleId` з шляху файлу.
+- Створює блокування з іменем `lint-<ruleId>`.
+- Використовує попередньо збережені результати для уникнення повторного виконання.
+- Повертає результат виконання.

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

@@ -0,0 +1,24 @@
+# run-standard-rule.mjs
+
+## Огляд
+
+Цей файл забезпечує публічний інтерфейс для оркестрування правил. Він обігріває виклик `discoverOneRule` до виконання правил, керуючи їхнім виконанням на основі контексту та політики. Це централізована точка інтеграції для запуску правил, забезпечуючи дедуплікацію та кешування для оптимізації продуктивності.
+
+## Поведінка
+
+1.  Отримує шлях до директорії правила.
+2.  Визначає ідентифікатор правила з назви директорії.
+3.  Отримує дані правила з директорії правила.
+4.  Отримує або створює кеш для прогону.
+5.  Запускає виконання правила, використовуючи отримані дані та кеш.
+6.  Забезпечує унікальний лок для паралельного запуску правила.
+7.  Повертає код успіху (0) або код помилки (1) в залежності від результатів виконання правила.
+
+## Гарантії поведінки
+
+- Виконання правил інкапсулює логіку `discoverOneRule` та `runRule`.
+- Виконання правил відбувається всередині блоку `withLock`.
+- Виконання правил дедублюється на основі стану git-дерева.
+- Різні правила можуть виконуватися паралельно.
+- Кеш використовується для зберігання результатів виконання правил в межах одного прогону.
+- Не допускається локальна логіка всередині правил. Розширення поведінки реалізується через опції контексту.

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

@@ -0,0 +1,31 @@
+# skill-meta.mjs
+
+## Огляд
+
+Цей файл парсить метадані скілу з файлу `meta.json` та надає інформацію про його конфігурацію. Він служить єдиним джерелом правди про скіл, замінюючи старий `auto.md`, і використовується для визначення, чи потрібно запускати скіл в окремому worktree, чи з кореня репозиторію. Це забезпечує узгодженість даних про скіли та полегшує їх використання в інших частинах системи.
+
+## Поведінка
+
+SKILL_ALWAYS: визначає літерал для безумовної автоактивації.
+parseSkillAutoSpec: перетворює значення `auto` з `meta.json` у об’єкт `SkillAutoSpec`.
+skillRequiresRoot: визначає, чи вимагає скіл запуску з кореня репо.
+readSkillMetaRaw: читає та парсить `meta.json` одного скіла, повертаючи розпарсений об’єкт або `null`.
+
+## Публічний API
+
+- SKILL_ALWAYS — Активує скіл завжди.
+- parseSkillAutoSpec — Перетворює специфікацію авто-скілу з JSON.
+- skillRequiresRoot — Перевіряє, чи потрібен скілу доступ до кореневої директорії.
+- readSkillMetaRaw — Зчитує та аналізує метадані скілу з файлу JSON.
+
+## Гарантії поведінки
+
+- Повертає `false` якщо не вдається розібрати `meta.json`.
+- Повертає `null` якщо не вдається визначити `auto.spec`.
+- `auto.spec` завжди є масивом id правил, якщо `auto.spec` визначено.
+- `worktree` має значення `true` лише для скілів, які потребують окремого git-worktree.
+- `requireRoot` має значення `true` лише для скілів, які мутують в CWD без worktree-ізоляції.
+- Якщо `worktree` має значення `true`, поле `requireRoot` не використовується.
+- Не використовує кеш.
+- Не кидає винятків.
+- Гарантує, що `meta.json` є єдиним джерелом правди для скілу.

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

@@ -0,0 +1,31 @@
+# sync-gitignore-worktree.mjs
+
+## Огляд
+
+Файл забезпечує, що кореневий `.gitignore` проєкту ігнорує локальні git-worktree. Він гарантує, що всі артефакти, пов'язані з worktree, правильно включені в `.gitignore`, забезпечуючи консистентність та уникнення непередбачуваних проблем. Це ключовий компонент системи завжди-активного flow/worktree-tooling.
+
+## Поведінка
+
+1.  Визначає корінь проєкту.
+2.  Перевіряє наявність в кореневому файлі `.gitignore` запису, що відповідає каталогу `.worktrees/`.
+3.  Якщо запису немає, викликає утиліту для додавання запису `.worktrees/` до `.gitignore`.
+4.  Утиліта додає запис, якщо його ще немає, інакше не робить нічого.
+5.  Повертає значення `true`, якщо запис було додано, інакше `false`.
+
+## Публічний API
+
+syncGitignoreWorktree — Синхронізує файл `.gitignore` в каталозі `worktrees` з кореневим файлом `.gitignore`.
+
+## Гарантії поведінки
+
+- Гарантує, що кореневий `.gitignore` проєкту ігнорує локальні git-worktree (`.worktrees/`).
+- Викликається з дефолтного sync (`npx \@nitra/cursor`) окремим top-level кроком.
+- Не викликається в контексті `syncClaudeConfig`.
+- `.worktrees/` є артефактом завжди-активного flow/worktree-tooling.
+- Один запис `.worktrees/` покриває каталог worktree та всі sibling-файли в ньому.
+- Запис безумовний, без гейта за `.n-cursor.json`-правилами.
+- Продюсер артефактів — завжди-активний flow.
+- Делегує наявній idempotent+append-only утиліті `ensureGitignoreEntries`.
+- `ensureGitignoreEntries` не перезаписує/не видаляє наявні рядки.
+- `ensureGitignoreEntries` створює `.gitignore`, якщо нема.
+- Не використовує кешування.

package/scripts/lib/docs/template.md

@@ -0,0 +1,40 @@
+# template.mjs
+
+## Огляд
+
+Файл обробляє шаблони для певних напрямків, збираючи їх у єдину структуру, яка індексується за назвою цільового файлу. Він повертає найбільш відповідний шаблон з `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,24 @@
+# timing-summary.mjs
+
+## Огляд
+
+Цей файл генерує табличне резюме часу виконання для команд `fix` та `lint`, які використовуються в orchestrator. Він підсумовує час виконання окремих правил та скриптів linting, надаючи інформацію для аналізу продуктивності. Результат представлений у вигляді рядка, який можна вивести для відображення користувачеві.
+
+## Поведінка
+
+formatDurationMs: Перетворює мілісекунди на рядок у форматі `<ціла>.<десята>s`.
+formatTimingSummary: Формує таблицю-резюме часу виконання з масиву записів, виводячи їх у текстовому форматі.
+
+## Публічний API
+
+- formatDurationMs — Форматує значення тривалості в форматі `<сек>.<десята>с`. Округлення виконується вниз (floor), щоб забезпечити консистентність результатів незалежно від платформи.
+- formatTimingSummary — Створює багаторядковий текст у форматі таблиці-резюме для виведення в консоль (stdout).
+
+## Гарантії поведінки
+
+❌ Якщо `ok` дорівнює `false`, повертає `null`.
+❌ Якщо час виконання перевищує 5 секунд, повертає `null`.
+Повертає рядок, що містить таблицю з часом виконання.
+Час виконання виражається у форматі `<ціла>.<десята>s`.
+Повертає рядок з символом `\n` в кінці.
+Не використовує кешування.

package/scripts/lib/docs/workspaces.md

@@ -0,0 +1,30 @@
+# workspaces.mjs
+
+## Огляд
+
+Цей файл визначає список кореневих каталогів пакетів у монорепо, використовуючи конфігурацію `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 @@
+# worktree-notice.mjs
+
+## Огляд
+
+Цей файл вбудовує інструкції щодо використання git-worktree, коли `meta.json.worktree` встановлено в `true`. Він забезпечує паралельне виконання скілу лише в окремому git-worktree, запобігаючи потенційним проблемам з паралелізмом. Цей механізм дозволяє уникнути гонки з CDN та забезпечує надійний запуск скілу з локальною копією CLI.
+
+## Поведінка
+
+WORKTREE_START: вставляє маркер початку worktree-блоку.
+WORKTREE_END: вставляє маркер кінця worktree-блоку.
+injectWorktreeNotice: вставляє або видаляє worktree-блок у `SKILL.md` на основі значення `meta.json.worktree`. Якщо `meta.json.worktree` `true`, вставляє блок; інакше видаляє. Якщо блок вже існує, замінює його; якщо ні — додає. Враховує наявність YAML-frontmatter та вставляє блок після нього. Використовує транслітерацію для створення суфікса гілки. Реалізує retry-обгортку для `npx` з обмеженням часу та інтервалом для перевірки.
+
+## Публічний API
+
+WORKTREE_START — Початок блоку worktree.
+WORKTREE_END — Кінець блоку worktree.
+injectWorktreeNotice — Змінює вміст SKILL.md, додаючи, оновлюючи або видаляючи worktree-блок.
+
+## Гарантії поведінки
+
+Якщо `meta.json.worktree === true`, то скіл виконується в окремому git-worktree.
+Скіл не паралелізується.
+Після створення worktree виконується `bun install` у цьому worktree.
+Виконується shell-обгортка `n_cursor_npx` навколо `npx` для bootstrap-виклику.
+Обгортка `n_cursor_npx` виконує retry на транзитні помилки реєстру/мережі (інтервал 30с, дефолт 5 хв, `N_CURSOR_NPX_RETRY_MAX_MIN`, ceiling 10 хв).
+При виникненні nonzero CLI повертається одразу.
+Команди, що вимагають command substitution, виконуються після створення worktree.

package/scripts/lib/docs/worktree.md

@@ -0,0 +1,38 @@
+# worktree.mjs
+
+## Огляд
+
+Файл містить детерміновану логіку для обробки гілок у `worktree-tool`, забезпечуючи безпечне перетворення імен гілок та створення описових файлів для `worktree`. Він використовується для генерації структури `.worktrees/` та ідентифікації неактивних описових файлів, що необхідно для операцій з видаленням. Це ключовий компонент для забезпечення консистентності та зручності роботи з `worktree-tool` безпосередньо з файловою системою.
+
+## Поведінка
+
+sanitizeBranch: Перетворює ім’я git-гілки на безпечне ім’я каталогу/файла для `.worktrees/`, замінюючи небезпечні символи на дефіс.
+firstFreeBranch: Знаходить першу вільну назву гілки, починаючи з заданої, і повертає її.
+worktreePaths: Створює абсолютні шляхи до checkout і файла-опису для заданої гілки.
+buildDescription: Генерує markdown-вміст файла-опису `.worktrees/<name>.md` на основі наданих параметрів.
+buildDirtyNotice: Створює повідомлення про незакомічені зміни основного дерева, якщо їх є, обмежуючи кількість відображених файлів.
+findOrphanDescFiles: Знаходить `.md`-описи, які не мають відповідного зареєстрованого worktree-checkout.
+
+## Публічний API
+
+- sanitizeBranch — Перетворює ім'я гілки на безпечне ім'я для каталогу/файлу.
+- firstFreeBranch — Знаходить першу вільну назву гілки, використовуючи суфікси `base`, `base2`, `base3` тощо.
+- worktreePaths — Визначає шляхи для checkout гілки та файлу опису.
+- buildDescription — Генерує текст опису для файлу опису worktree.
+- buildDirtyNotice — Виводить повідомлення про незакомічені зміни, які не включені у worktree.
+- findOrphanDescFiles — Знаходить `.md`-описи, що не мають відповідного worktree-checkout.
+
+## Гарантії поведінки
+
+- `sanitizeBranch` повертає строку, безпечну для використання в шляхах файлової системи.
+- `sanitizeBranch` не змінює вхідну строку.
+- `worktreePaths` повертає масив з двох строк, що представляють шлях до checkout та файлу опису.
+- `worktreePaths` гарантує, що обидва шляхи є дійсними.
+- `buildDescription` повертає строку, що відповідає конвенції `worktree.mdc`.
+- `buildDescription` не змінює вхідну строку.
+- `findOrphanDescFiles` повертає масив з рядків, що представляють шляхи до файлів опису.
+- `findOrphanDescFiles` гарантує, що всі рядки в масиві є дійсними шляхами файлів.
+- Функції не викликають жодних побічних ефектів, що впливають на стан файлової системи.
+- Функції не взаємодіють з Git або будь-якими іншими системами контролю версій.
+- Результат роботи функцій не залежить від будь-яких зовнішніх факторів.
+- Функції не використовують жодного кешу.