@nitra/cursor 5.1.0 → 5.2.1

package/rules/docker/lint/docs/lint.md

@@ -1,3 +1,9 @@
+---
+docgen:
+  source: npm/rules/docker/lint/lint.mjs
+  crc: 98a98d10
+---
+
 # lint.mjs — реалізація підкоманди `lint-docker`
 
 ## Огляд
@@ -165,11 +171,13 @@ if (isRunAsCli(import.meta.url)) {
 
 - **CLI:** `bun run n-cursor lint-docker` (або відповідний bin-скрипт) — основний сценарій.
 - **Програмно з інших скриптів:**
+
   ```js
   import { runLintDocker } from 'npm/rules/docker/lint/lint.mjs'
-  
+
   const code = await runLintDocker() // 0 — OK, 1 — є зауваження/помилки
   ```
+
 - **Тести/допоміжний код:**
 
   ```js

package/rules/efes/docs/fix.md

@@ -1,3 +1,9 @@
+---
+docgen:
+  source: npm/rules/efes/fix.mjs
+  crc: 12fc1644
+---
+
 # `fix.mjs` — entry-point правила `efes`
 
 ## Огляд

package/rules/feedback/docs/fix.md

@@ -1,140 +1,30 @@
-# `npm/rules/feedback/fix.mjs`
+---
+docgen:
+  source: npm/rules/feedback/fix.mjs
+  crc: 12fc1644
+  score: 100
+---
 
-## Огляд
-
-Файл є точкою входу (entry-point) для правила `feedback` у CLI-наборі `@nitra/cursor`. Він реалізує дві паралельні ролі того ж самого модуля:
-
-1. **Library mode** — експортує функцію `run(ctx)`, яку викликають інші частини оркестратора (наприклад, агрегований `fix`/`lint`-прогін, де всі правила запускаються послідовно з шарінгом кешу обходу файлів `walkCache`).
-2. **Standalone mode** — якщо файл стартує безпосередньо як CLI-скрипт (`bun rules/feedback/fix.mjs`), він виконується як повний аналог команди `npx @nitra/cursor fix feedback` із завантаженням конфігу, застосуванням whitelist та підсумком.
-
-Сам файл логіки правила не містить — він є тонким адаптером, що делегує роботу до спільного раннера `runStandardRule`. Стандартний потік правила, який запускається через цей адаптер: `applies → JS-concerns → policy → mdc-refs` (тобто перевіряється застосовність до проєкту, далі — JS-специфічні перевірки, далі — policy-шар, наприкінці — синхронізація посилань у відповідному `.mdc`-файлі).
-
-Модуль використовує `import.meta.dirname`, тому він повністю прив'язаний до місця свого розташування: каталог правила (`npm/rules/feedback/`) автоматично стає коренем, у якому раннер шукає `meta.json`, `feedback.mdc` та інші артефакти.
-
-## Експорти / API
-
-| Експорт | Тип                               | Призначення                                                                                          |
-| ------- | --------------------------------- | ---------------------------------------------------------------------------------------------------- |
-| `run`   | `function(ctx?): Promise<number>` | Library-точка входу правила. Викликається оркестратором; повертає exit-code (0 — OK, 1 — порушення). |
-
-Side-експортів немає. Default-експорту немає.
-
-Поведінка при прямому запуску файлу як CLI (через `process.exit(await runRuleCli(...))`) — це не експорт, а top-level side-effect, активний лише коли `isRunAsCli(import.meta.url)` повертає `true`.
-
-## Функції
-
-### `run(ctx)`
-
-```js
-export function run(ctx)
-```
-
-- **Призначення:** запустити правило `feedback` у library-режимі. Делегує всю роботу до `runStandardRule`, передаючи каталог поточного файлу як ідентифікатор правила.
-- **Параметри:**
-  - `ctx` — `RuleContext | undefined`. Опціональний контекст прогону. Тип імпортується через JSDoc-посилання `import('../../scripts/lib/run-standard-rule.mjs').RuleContext`. Зокрема, контекст несе спільні структури між правилами (наприклад, `walkCache` — кеш обходу файлової системи, щоб не сканувати дерево кілька разів у разі прогону кількох правил поспіль). Якщо `ctx` не переданий, `runStandardRule` створює власний внутрішній контекст.
-- **Повертає:** `Promise<number>` — exit-code:
-  - `0` — правило застосовне і порушень не знайдено, або правило не застосовне до поточного проєкту (`applies` повернув `false`);
-  - `1` — знайдені порушення (policy / JS-concerns / mdc-refs).
-- **Side effects:** жодних прямих у цій функції. Опосередковано через `runStandardRule` можливі: читання файлів проєкту, читання `meta.json` і `feedback.mdc`, лог у stdout/stderr, мутація переданого `walkCache`.
-- **Винятки:** функція сама не кидає; будь-яка помилка приходить як rejected promise від `runStandardRule`.
-
-### Top-level standalone-блок
-
-```js
-if (isRunAsCli(import.meta.url)) {
-  process.exit(await runRuleCli(import.meta.dirname))
-}
-```
-
-- **Призначення:** перетворити цей же модуль на CLI-скрипт. Якщо файл був запущений напряму (а не імпортований), виконується повний CLI-цикл правила — еквівалент `npx @nitra/cursor fix feedback`.
-- **Виклик:** `runRuleCli(import.meta.dirname)` отримує абсолютний шлях до каталогу правила; всередині раннера це задає, який саме `meta.json`/`*.mdc` і `applies/policy/...`-функції підтягуються.
-- **Повертає / завершення:** результат `runRuleCli` (число) йде в `process.exit(...)`, тобто процес одразу завершується з відповідним exit-code. Це навмисно: standalone entry-point має повернути код виходу для CI/IDE-інтеграцій.
-- **Спеціальні маркери:**
-  - `// eslint-disable-next-line n/no-process-exit, unicorn/no-process-exit` — свідома відмова від загальної заборони `process.exit` саме тут, бо це standalone-точка входу.
-- **Side effects:** завершує процес Node/Bun.
-
-## Залежності
+# fix.mjs
 
-Файл імпортує два внутрішні модулі (relative-шляхи, без зовнішніх npm-пакетів):
-
-| Імпорт            | З файлу                                   | Що використовується                     | Роль                                                                                                                                                   |
-| ----------------- | ----------------------------------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `isRunAsCli`      | `../../scripts/lib/run-rule-cli.mjs`      | Функція-предикат                        | Визначає, чи цей `.mjs`-файл був запущений напряму як CLI (через `import.meta.url`), а не імпортований як модуль.                                      |
-| `runRuleCli`      | `../../scripts/lib/run-rule-cli.mjs`      | Async-функція                           | Виконує повний CLI-цикл правила: завантаження конфігу, whitelist-фільтрацію, прогін стандартного раннера, форматування підсумку, повернення exit-code. |
-| `runStandardRule` | `../../scripts/lib/run-standard-rule.mjs` | Async-функція + JSDoc-тип `RuleContext` | Стандартний раннер для правил: `applies → JS-concerns → policy → mdc-refs`. Шукає артефакти у переданому каталозі.                                     |
-
-Глобали з рантайму:
-
-- `import.meta.dirname` — абсолютний шлях каталогу поточного `.mjs`-файлу (Bun / Node ≥ 20.11). Використовується як «корінь правила».
-- `import.meta.url` — file-URL модуля; передається в `isRunAsCli` для надійного порівняння з `process.argv[1]`.
-- `process.exit` — викликається лише у standalone-гілці.
-
-Зовнішні пакети не імпортуються.
-
-## Потік виконання / Використання
-
-### Сценарій A — імпорт як library
-
-```js
-import { run } from './npm/rules/feedback/fix.mjs'
-
-const code = await run(/* ctx */)
-if (code !== 0) {
-  // правило знайшло порушення
-}
-```
-
-Послідовність всередині:
-
-1. Викликається `run(ctx)`.
-2. `run` повертає `runStandardRule(import.meta.dirname, ctx)`.
-3. Усередині `runStandardRule`:
-   - перевіряє `applies` (чи правило застосовне до проєкту);
-   - проганяє JS-concerns (lint/structure);
-   - проганяє policy-перевірки;
-   - звіряє `mdc-refs` (узгодженість посилань між кодом і `feedback.mdc`).
-4. Повертається `0` або `1`.
-
-Top-level `if (isRunAsCli(...))` у цьому випадку не спрацьовує — `isRunAsCli(import.meta.url)` повертає `false`, бо стартова точка процесу — інший файл.
-
-### Сценарій B — прямий запуск як CLI
-
-```bash
-bun npm/rules/feedback/fix.mjs
-# або еквівалент:
-npx @nitra/cursor fix feedback
-```
-
-Послідовність:
-
-1. Node/Bun завантажує модуль; виконуються `import`-и.
-2. Перевіряється `isRunAsCli(import.meta.url)` → `true`.
-3. Викликається `await runRuleCli(import.meta.dirname)`. Цей раннер:
-   - завантажує загальний конфіг проєкту;
-   - застосовує whitelist (якщо в конфізі обмежений набір правил);
-   - всередині все одно проганяє ту ж саму `runStandardRule`-логіку;
-   - друкує форматований summary;
-   - повертає exit-code.
-4. `process.exit(code)` миттєво завершує процес із отриманим кодом, який потім читає CI/IDE.
-
-### Чому дві ролі в одному файлі
+## Огляд
 
-Конвенція в `npm/rules/<id>/fix.mjs` дозволяє:
+Модуль виконує задану перевірку, ініціалізуючи її з локального файлу конфігурації. При запуску як окрема програма, він завантажує конфігурацію, перевіряє білий список та надає звіт про результати виконання. Результат виконання правила повертається як код виходу.
 
-- оркестратору проганяти всі правила одним процесом, шарячи `walkCache` (швидко, для batch-режимів);
-- розробнику запустити **одне** правило точково з шелла без обгорток і отримати CI-сумісний exit-code.
+## Поведінка
 
-Жодного дублювання логіки немає — обидві гілки в кінцевому рахунку викликають один і той самий `runStandardRule`, просто standalone-гілка додає шар CLI-обгортки (`runRuleCli`).
+1. Викликається функція `run` для виконання правила.
+2. Виконання правила відбувається шляхом ініціалізації стандартного правила з директорії цього файлу.
+3. Якщо код виконується як окрема утиліта (standalone), ініціюється повний запуск правила.
+4. Запуск правила як окремої утиліти включає завантаження конфігурації, перевірку білого списку та підведення підсумків.
+5. Результат цього запуску повертається як код виходу.
 
-## Rebuild Test
+## Публічний API
 
-Чи можна за цим документом без доступу до файлу відтворити модуль еквівалентної поведінки? Так:
+run — виконує послідовність перевірок: застосовує правила, аналізує JS-занепокоєння, порівнює з політикою та перевіряє посилання MDC.
 
-- ім'я експорту: `run`, сигнатура `(ctx) => Promise<number>`;
-- тіло: `return runStandardRule(import.meta.dirname, ctx)`;
-- top-level `if`: `isRunAsCli(import.meta.url)` → `process.exit(await runRuleCli(import.meta.dirname))`;
-- два імпорти з точно вказаних шляхів (`../../scripts/lib/run-rule-cli.mjs` для `isRunAsCli`/`runRuleCli`, `../../scripts/lib/run-standard-rule.mjs` для `runStandardRule`);
-- ESLint-disable коментар над `process.exit` для `n/no-process-exit` і `unicorn/no-process-exit`;
-- JSDoc-блок над `run` із посиланням на тип `RuleContext` через `import('...')`-нотацію.
+## Гарантії поведінки
 
-Усі ці елементи описані вище — реконструкція еквівалентного файлу можлива.
+- Read-only: файл не виконує операцій запису у файлову систему.
+- Кешує результати в межах одного прогону.
+- Не звертається до мережі.

package/rules/ga/docs/fix.md

@@ -1,25 +1,27 @@
+---
+docgen:
+  source: npm/rules/ga/fix.mjs
+  crc: 12fc1644
+  score: 100
+---
+
 # fix.mjs
 
 ## Огляд
 
-Цей файл запускає процес перевірки наявності та стану необхідних системних ресурсів. Він забезпечує швидку оцінку готовності системи до подальшої роботи, використовуючи кешовані дані для прискорення процесу. Результати перевірки використовуються для прийняття рішень щодо подальших дій.
+Модуль відповідає за запуск механізму виконання стандартного правила. Він шукає та застосовує правила, використовуючи поточний каталог як джерело. При запуску як окрема програма, він ініціює виконання команди, необхідної для застосування цього правила.
 
 ## Поведінка
 
-1.  Ініціалізує контекст прогону.
-2.  Викликає стандартне правило, використовуючи контекст.
-3.  Якщо код виконується як окремий CLI-скрипт, то:
-    1.  Викликає оркестрацію правил.
-    2.  Повертає код завершення процесу.
+1. Викликає механізм виконання стандартного правила, використовуючи поточний каталог як джерело правил.
+2. Якщо скрипт виконується як окрема програма, запускає оркестрацію командного рядка для виконання правила.
 
 ## Публічний API
 
-- run — Запускає стандартне правило, враховуючи контекст та перетворюючи його на JS-коду, політику та посилання на MDC.
-- Library mode — Викликається через CLI-оркестрацію за допомогою імпорту та функції `run`.
+run — виконує послідовність дій: застосовує правила, обробляє JS-занепокоєння, перевіряє політику та посилання MDC.
 
 ## Гарантії поведінки
 
-- Запускає процес.
-- Кеш зберігає результати попередніх прогонів.
-- Результат залежить від попередніх прогонів.
-- Немає взаємодії з мережею.
+- Read-only: файл не виконує операцій запису у файлову систему.
+- Кешує результати в межах одного прогону.
+- Не звертається до мережі.

package/rules/ga/js/docs/lint.md

@@ -1,19 +1,22 @@
+---
+docgen:
+  source: npm/rules/ga/js/lint.mjs
+  crc: 428bf482
+  score: 100
+---
+
 # lint.mjs
 
 ## Огляд
 
-Файл `lint` делегує перевірку коду інструменту, який запускається з командного рядка. Він використовується для автоматизованої перевірки коду на відповідність певним правилам. Це забезпечує консистентність та якість коду в проєкті.
+Делегує застосування правил зовнішньому інструменту командного рядка. Параметр `files` ігнорується, оскільки режим перевірки на рівні окремих файлів відсутній. Публічна функція `lint` повертає код виходу інструменту, який визначає успішність або невдачу перевірки.
 
 ## Поведінка
 
-1.  Запускає наявний CLI для перевірки правил.
-2.  Проводить аналіз всього репозиторію, ігноруючи вказаний список файлів.
-3.  Повертає код завершення процесу.
-4.  Не використовує кеш результатів.
-5.  Не здійснює взаємодії з мережею.
+1. Викликає зовнішній інструмент для перевірки коду.
+2. Повертає код виходу цього інструменту.
 
 ## Гарантії поведінки
 
-- Делегує правила до існуючого CLI.
-- Не враховує `files` в режимі per-file.
-- Не має кешування.
+- Read-only: файл не виконує операцій запису у файлову систему.
+- Не звертається до мережі.

package/rules/ga/js/docs/workflows.md

@@ -1,32 +1,33 @@
+---
+docgen:
+  source: npm/rules/ga/js/workflows.mjs
+  crc: a9296cf1
+  score: 100
+---
+
 # workflows.mjs
 
 ## Огляд
 
-Файл перевіряє GitHub Actions workflows на відповідність певним правилам та стандартам. Він забезпечує консистентність та якість workflow, виявляючи потенційні проблеми, такі як відсутність clean/lint workflow або використання непідтримуваних інструментів. Це частина автоматизованого процесу забезпечення дотримання найкращих практик при розробці GitHub Actions.
+Модуль виявляє наявність інструменту `shellcheck` та підтверджує відповідність конфігурації проєкту правилам ga.mdc. Він перевіряє відповідність workflow-файлів Rego-полісі, наявність обов'язкових компонентів та коректність шляхів тригерів GitHub Actions. Модуль свідомо пропускає шляхи `.github` та `.git` під час перевірки.
 
 ## Поведінка
 
-- `checkShellcheckInstalled`: Перевіряє наявність бінарника `shellcheck` в системному PATH.
-- `checkGaWorkflowFiles`: Перевіряє наявність workflow-файлів з розширенням `.yml` та відсутність інших розширень.
-- `runAllGaRego`: Запускає Rego-перевірки для всіх workflow-файлів, використовуючи `conftest` для аналізу.
-- `check`: Координує всі перевірки, включаючи Rego-аналіз, перевірку workflow-структури та перевірку наявність файлів.
+checkShellcheckInstalled перевіряє наявність бінарника `shellcheck` у системному шляху, щоб забезпечити узгодженість локальних та CI-перевірок (ga.mdc).
+check виконує комплексну валідацію конфігурації проєкту щодо правил ga.mdc, включаючи структурну перевірку workflow-файлів за допомогою Rego-полісі, перевірку наявності обов'язкових компонентів, валідацію шляхів тригерів GitHub Actions, пошук залишків MegaLinter та перевірку наявності `shellcheck` (ga.mdc). При цьому ігнорує директорії `.github` та `.git`.
 
 ## Публічний API
 
-- checkShellcheckInstalled — Перевіряє наявність `shellcheck` у системі та зупиняє workflow, якщо його немає.
-- check — Перевіряє відповідність проєкту правилам валідації.
-- runAllGaRego — Запускає Rego-перевірку правил, як перший етап валідації.
-- lint-ga — Запускає перевірку `bun lint-ga` з використанням `actionlint` та `zizmor`.
+checkShellcheckInstalled — визначає, чи встановлено `shellcheck` у системному шляху. Це дозволяє `actionlint` запускати перевірки скриптів лише тоді, коли інструмент доступний локально.
+
+check — порівнює структуру проєкту з вимогами, визначеними у правилах (ga.mdc).
+
+Plan B-патерн — виконує первинну перевірку структури робочого процесу за допомогою Rego-полісі. Потім виконує перевірки на рівні JavaScript, включаючи пошук файлів та конфігурацій. Команда `bun run lint-ga` повторно викликає цю ж перевірку, використовуючи зовнішні інструменти.
 
 ## Гарантії поведінки
 
-- Гарантується наявність файлів `package.json`, `.vscode/*` та `.github/zizmor.yml`.
-- Гарантується, що workflow використовує `actions/checkout@v6` перед локальними операціями.
-- Гарантується, що workflow використовує composite action `action.yml` з `npx @nitra/cursor`.
-- Гарантується, що workflow містить `clean-ga-workflows.yml`, `clean-merged-branch.yml`, `lint-ga.yml` та `git-ai.yml`.
-- Гарантується, що workflow використовує `concurrency` для паралельного виконання.
-- Гарантується, що workflow не містить `oven-sh/setup-bun`, `actions/cache`, `bun install` у `uses` або `run`.
-- Гарантується, що workflow не використовує shell-продовження `\` у `run`.
-- Гарантується, що workflow використовує `shellcheck` локально.
-- Гарантується, що workflow перевіряє наявність файлів за допомогою `git ls-files :(glob)` та `on.*.paths`.
-- Гарантується, що workflow перевіряє наявність файлів, що залишилися від MegaLinter.
+- Read-only: файл не виконує операцій запису у файлову систему.
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).
+- За невдалої перевірки повертає `false`/`null` замість винятку.
+- Свідомо пропускає шляхи: `.github`, `.git`.
+- Не звертається до мережі.

package/rules/ga/lint/docs/lint.md

@@ -1,3 +1,9 @@
+---
+docgen:
+  source: npm/rules/ga/lint/lint.mjs
+  crc: c391782d
+---
+
 # lint.mjs
 
 ## Огляд

package/rules/graphql/docs/fix.md

@@ -1,3 +1,9 @@
+---
+docgen:
+  source: npm/rules/graphql/fix.mjs
+  crc: 12fc1644
+---
+
 # `npm/rules/graphql/fix.mjs`
 
 ## Огляд