@nitra/cursor 3.22.0 → 3.23.1

package/rules/ga/docs/fix.md

@@ -0,0 +1,158 @@
+# fix.mjs — точка входу правила `ga`
+
+## Огляд
+
+Файл `npm/rules/ga/fix.mjs` — це **подвійна точка входу** (dual-mode entry-point) для правила з ідентифікатором `ga` (Google Analytics) у проєкті `@nitra/cursor`. Файл реалізує дві ролі одночасно:
+
+1. **Library mode** — експортує функцію `run(ctx)`, яку імпортує оркестратор CLI (`bin/cursor.mjs` або інші правила) для запуску прогону у складі сукупної команди (наприклад, `npx @nitra/cursor fix`).
+2. **Standalone mode** — якщо файл запущено напряму через `bun npm/rules/ga/fix.mjs` (або `node ...`), він самостійно ініціалізує CLI-обгортку (`runRuleCli`) і завершує процес із кодом виходу, придатним для CI/IDE.
+
+Логіка самого правила інкапсульована в утиліті `runStandardRule`, яка послідовно виконує стандартний пайплайн усіх «standard»-правил репозиторію:
+
+- **applies** — перевірка, що правило застосовне до поточного workspace/файлів (за патернами з `meta.json`);
+- **JS-concerns** — запуск перевірок (`check-*.mjs`) і авто-фіксерів (`fix-*.mjs`) із підтек `js/`, `lint/`;
+- **policy** — застосування policy-перевірок із підтеки `policy/`;
+- **mdc-refs** — валідація посилань всередині `ga.mdc` (cross-link integrity).
+
+Файл свідомо мінімалістичний: він **не містить власної бізнес-логіки**, лише делегує виконання у спільні бібліотеки `scripts/lib/*`. Це гарантує однакову поведінку для всіх правил пакету.
+
+## Експорти / API
+
+| Експорт | Тип                               | Опис                                                                                                                               |
+| ------- | --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| `run`   | `function(ctx?): Promise<number>` | Бібліотечний вхід; запускає стандартний пайплайн правила в контексті переданого `ctx`. Повертає exit-code (0 — OK, 1 — порушення). |
+
+Default-експорту немає. Файл не реекспортує жодних інших символів.
+
+## Функції
+
+### `run(ctx)`
+
+Бібліотечний інтерфейс правила. Дозволяє оркестратору CLI або іншим правилам запустити перевірку `ga` без створення нового процесу.
+
+**Сигнатура:**
+
+```js
+export function run(ctx)
+```
+
+**Параметри:**
+
+- `ctx` (`RuleContext`, опційний) — контекст прогону, типізований через JSDoc-імпорт з `../../scripts/lib/run-standard-rule.mjs`. Типово містить:
+  - `walkCache` — кеш обходу файлів (щоб уникнути повторного `readdir` між правилами в одній сесії);
+  - інші поля, передбачені реалізацією `runStandardRule` (репорти, прапорці dry-run тощо).
+
+**Повертає:**
+
+- `Promise<number>` — числовий код виходу:
+  - `0` — правило не знайшло порушень або всі знайдені були автоматично виправлені;
+  - `1` — залишилися порушення, які потребують ручного втручання.
+
+**Side effects:**
+
+- Може читати файли проєкту (через walkCache і внутрішні `check-*.mjs`/`fix-*.mjs`);
+- Може **писати** файли (auto-fix у режимі за замовчуванням; `fix-*.mjs` із підтек `js/`, `lint/`, `policy/`);
+- Може писати в `stdout`/`stderr` (репорти, попередження, summary), залежно від конфігурації `runStandardRule`;
+- Не викликає `process.exit` напряму — повертає код виходу як значення Promise.
+
+**Внутрішня реалізація:**
+
+```js
+return runStandardRule(import.meta.dirname, ctx)
+```
+
+Передає **абсолютний шлях до директорії правила** (`import.meta.dirname` — Node/Bun-нативний спосіб отримати `__dirname` в ESM) і контекст. `runStandardRule` сам визначить ID правила за назвою теки (`ga`), завантажить `meta.json`, `ga.mdc` і виконає пайплайн.
+
+### Standalone-блок (top-level `if`)
+
+Не є експортованою функцією, але є важливою частиною API файлу.
+
+**Логіка:**
+
+```js
+if (isRunAsCli(import.meta.url)) {
+  process.exit(await runRuleCli(import.meta.dirname))
+}
+```
+
+**Поведінка:**
+
+- `isRunAsCli(import.meta.url)` повертає `true`, якщо файл був запущений як основний модуль (а не імпортований). Це Bun/Node-сумісна заміна звичайного для CommonJS `require.main === module`.
+- У такому разі викликається `runRuleCli(import.meta.dirname)` — обгортка, що додає до простого `run(ctx)`:
+  - парсинг аргументів командного рядка (наприклад, `--dry-run`, `--scope`);
+  - завантаження користувацького конфігу (`.cursorrc`, whitelist-файлів);
+  - друк фінального summary з кодом виходу.
+- Результат (`number`) передається у `process.exit(...)`, тож виклик `bun npm/rules/ga/fix.mjs` повертає shell-у точний exit-code для CI/IDE-інтеграції.
+
+**ESLint-винятки** (інлайн-коментар):
+
+- `n/no-process-exit` (плагін `eslint-plugin-n`) і `unicorn/no-process-exit` — обидва зазвичай забороняють `process.exit`, оскільки він обриває async-операції без cleanup. Тут виняток виправданий: це **єдиний standalone entry-point**, який мусить повернути exit-code саме через `process.exit`, інакше CI не зможе розрізнити успіх/провал.
+
+**Top-level `await`:**
+
+- Використовується `await runRuleCli(...)` на верхньому рівні модуля — це валідно для ESM (`.mjs`) у сучасних Node.js (≥14.8) і Bun. Без `await` `process.exit` отримав би `Promise` замість числа.
+
+## Залежності
+
+### Внутрішні (workspace)
+
+| Модуль              | Шлях                                      | Експорти, що використовуються                                       |
+| ------------------- | ----------------------------------------- | ------------------------------------------------------------------- |
+| `run-rule-cli`      | `../../scripts/lib/run-rule-cli.mjs`      | `isRunAsCli`, `runRuleCli`                                          |
+| `run-standard-rule` | `../../scripts/lib/run-standard-rule.mjs` | `runStandardRule`; також імпортується тип `RuleContext` через JSDoc |
+
+Шляхи відносні до `npm/rules/ga/fix.mjs`, тобто `../../scripts/lib/` → `npm/scripts/lib/`.
+
+### Зовнішні / runtime
+
+- **Node.js / Bun ESM API**: `import.meta.url`, `import.meta.dirname` (вимагає Node ≥20.11 або Bun, де `dirname` доступний нативно).
+- **`process`**: глобальний об'єкт (`process.exit`).
+
+Жодних npm-залежностей файл напряму не імпортує — всі стороні пакети підтягуються транзитивно через `scripts/lib/*`.
+
+## Потік виконання / Використання
+
+### Сценарій 1: запуск через `@nitra/cursor` (library mode)
+
+1. Користувач виконує `npx @nitra/cursor fix ga` або `npx @nitra/cursor fix` (усі правила).
+2. CLI-бінарник пакету (`bin/cursor.mjs` або аналог) динамічно імпортує `npm/rules/ga/fix.mjs`.
+3. Оскільки модуль імпортовано (а не запущено), `isRunAsCli(import.meta.url)` → `false`, standalone-блок не виконується.
+4. CLI викликає експортовану `run(ctx)` із заздалегідь підготованим контекстом (`walkCache`, прапорці).
+5. `run` повертає `Promise<number>` — CLI агрегує його з результатами інших правил у фінальний exit-code.
+
+### Сценарій 2: прямий запуск файлу (standalone)
+
+1. Розробник або CI виконує `bun npm/rules/ga/fix.mjs` (зручно для дебагу одного правила).
+2. Модуль завантажується як основний; `isRunAsCli(import.meta.url)` → `true`.
+3. Виконується `await runRuleCli(import.meta.dirname)`:
+   - парсяться CLI-аргументи;
+   - завантажується конфіг/whitelist;
+   - всередині також викликається `runStandardRule` (так само як у library-режимі), але з повним «end-to-end» обрамленням;
+   - виводиться summary.
+4. `process.exit(<code>)` завершує процес із отриманим exit-code (0/1).
+
+### Стандартний пайплайн `runStandardRule` (у обох сценаріях)
+
+Послідовність (детальніше — в документації `runStandardRule`):
+
+1. **applies** — `meta.json` визначає, чи треба запускати правило в поточному workspace; якщо ні — ранній вихід з кодом 0.
+2. **JS-concerns** — обходяться підтеки правила (`js/`, `lint/`), виконуються пари `check-*.mjs` + `fix-*.mjs`. Якщо `check` повернув порушення, відповідний `fix` пробує їх прибрати.
+3. **policy** — з підтеки `policy/` запускаються policy-чекери (зазвичай це декларативні правила, без auto-fix або з обмеженим fix).
+4. **mdc-refs** — валідація, що в `ga.mdc` (markdown-документ із описом правила) посилання на `js/`, `lint/`, `policy/` коректні (немає «битих» референсів).
+5. Агрегується фінальний exit-code: `0`, якщо всі стадії чисті; `1` — інакше.
+
+### Як додати/змінити поведінку правила `ga`
+
+Файл `fix.mjs` змінювати **не треба** — він універсальний. Щоб модифікувати поведінку правила:
+
+- додайте/змініть `check-*.mjs` і `fix-*.mjs` у підтеках `js/`, `lint/` теки `ga/`;
+- оновіть `policy/`-чекери для декларативних обмежень;
+- актуалізуйте `ga.mdc` (опис для людини/LLM) і `meta.json` (applies, scope, прапорці);
+- запустіть `bun npm/rules/ga/fix.mjs` для локальної перевірки.
+
+### Обмеження та інваріанти
+
+- Файл **повинен** залишатися мінімалістичним — будь-яка бізнес-логіка в `fix.mjs` правила вважається порушенням архітектури «standard rule» (див. `n-ci4.mdc`).
+- Не можна вилучати `if (isRunAsCli(...))`-блок: інакше прямий запуск файлу не поверне CI exit-code.
+- Не можна замінювати `process.exit` на `return` у standalone-блоці: top-level `return` у ESM-модулі недопустимий, а без `process.exit` процес не отримає правильний код.
+- ESLint-винятки (`n/no-process-exit`, `unicorn/no-process-exit`) застосовуються **лише** до рядка з `process.exit` — їх не слід розширювати на інші місця.

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

@@ -0,0 +1,100 @@
+# `npm/rules/ga/js/lint.mjs`
+
+## Огляд
+
+Файл `lint.mjs` у теці `npm/rules/ga/js/` є тонкою адаптерною ланкою (CI-кроком) правила `ga` (GitHub Actions). Він не реалізує жодної самостійної логіки лінтингу — натомість делегує виклик у канонічну CLI-обгортку правила, яка живе у сусідньому модулі `npm/rules/ga/lint/lint.mjs` (експортує `runLintGaCli`).
+
+Призначення модуля — надати уніфікований lint-entry для правила `ga`, який відповідає інтерфейсному контракту «JS-частини правила» (експорт `async function lint(files)`), і одночасно явно зафіксувати, що правило `ga` працює **тільки в whole-repo режимі**: per-file-аналіз не підтримується, а вхідний аргумент `files` ігнорується.
+
+Контекст:
+
+- Правило `ga` перевіряє конфіги GitHub Actions (`.github/workflows/*.{yml,yaml}`) — як через Rego (conftest), так і через JS cross-file-перевірки в `npm/rules/ga/js/workflows.mjs`.
+- Канонічний CLI правила (`runLintGaCli`) у `npm/rules/ga/lint/lint.mjs` додатково запускає preflight для зовнішніх інструментів (`shellcheck`, `conftest`, `uv`/`uvx`), а потім послідовно — `bunx github-actionlint`, `uvx zizmor --offline --collect=workflows .` і делегує далі.
+- Сам адаптер `npm/rules/ga/js/lint.mjs` лише викликає цей CLI і повертає його exit code.
+
+## Експорти / API
+
+Модуль є ES-модулем (`.mjs`) з одним публічним експортом.
+
+| Експорт | Тип                                                    | Призначення                                                                                                               |
+| ------- | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------- |
+| `lint`  | `async function (files?: string[]) => Promise<number>` | CI-крок (whole-repo lint) для правила `ga`. Параметр `files` ігнорується. Повертає exit code від канонічного CLI правила. |
+
+Інших експортів (`default`, named) у файлі немає.
+
+## Функції
+
+### `lint(_files)`
+
+Єдина функція файлу. Адаптер навколо `runLintGaCli`.
+
+- **Сигнатура:**
+  ```
+  async function lint(_files: string[] | undefined): Promise<number>
+  ```
+- **Параметри:**
+  - `_files` — `string[] | undefined`. **Ігнорується.** Префікс `_` у назві параметра — конвенційний маркер «не використовується». Документація в JSDoc явно вказує: «whole-repo аналіз», per-file режиму немає. Аргумент усе одно приймається, щоб задовольнити загальний контракт «JS-частини правила» (інші правила можуть мати per-file lint, який отримує список змінених файлів).
+- **Повертає:** `Promise<number>` — exit code, отриманий від `runLintGaCli()`. Семантика стандартна для CLI: `0` — успіх, ненульове — помилка/порушення.
+- **Виключення:** функція сама не кидає винятків і не обгортає `runLintGaCli` у `try/catch`. Будь-яка нерозвʼязана `Promise` чи синхронний `throw` всередині `runLintGaCli` пробʼється назовні без модифікації.
+- **Side effects:** прямих side effects сам адаптер не виконує. Усі side effects (preflight installs через `ensureTool`, запуск зовнішніх процесів `bunx github-actionlint`, `uvx zizmor`, `conftest`, друк у stdout/stderr, можливі мутації CWD) — на стороні `runLintGaCli` та модулів, до яких він делегує далі (`rules/ga/fix.mjs::check()`, Rego-полісі `npm/policy/ga/`, JS-перевірки `workflows.mjs`).
+
+## Залежності
+
+### Імпорти
+
+| Імпорт         | Шлях                 | Тип                                                                          | Призначення                                                                                                           |
+| -------------- | -------------------- | ---------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
+| `runLintGaCli` | `'../lint/lint.mjs'` | Іменований імпорт із сусіднього модуля (відносний шлях у межах правила `ga`) | Канонічний CLI правила `ga`: робить preflight, виконує `actionlint`, `zizmor`, делегує в `rules/ga/fix.mjs::check()`. |
+
+Інших імпортів немає — ані вбудованих модулів Node, ані сторонніх npm-пакетів.
+
+### Транзитивні залежності (інформативно)
+
+Через `runLintGaCli` адаптер опосередковано залежить від:
+
+- `node:process` (платформа);
+- внутрішніх хелперів `npm/scripts/lib/`: `ensureTool`, `runLintStep`, `runStandardLint`;
+- утиліти `npm/scripts/utils/resolve-cmd.mjs`;
+- JS-перевірок правила `ga` у `npm/rules/ga/js/workflows.mjs` (експорт `check`);
+- Rego-полісі `npm/policy/ga/` (через `runConftestBatch` у `rules/ga/fix.mjs`);
+- зовнішніх бінарників: `bunx`, `github-actionlint`, `shellcheck`, `uv`/`uvx`, `zizmor`, `conftest`.
+
+Прямого знання про ці транзитивні залежності адаптер не має — для нього існує тільки контракт «`runLintGaCli` повертає `Promise<number>` з exit code».
+
+## Потік виконання / Використання
+
+### Внутрішній потік
+
+1. Викликається `lint(_files)`.
+2. Параметр `_files` приймається й ігнорується (whole-repo режим).
+3. Викликається `runLintGaCli()` без аргументів.
+4. Результат (`Promise<number>`) повертається безпосередньо викликачу через `return runLintGaCli()`. Жодного `await` тут немає — функція позначена `async`, тому повернутий проміс автоматично «розтекстується» у проміс async-функції; виклик семантично еквівалентний `return await runLintGaCli()`.
+
+### Як використовується
+
+Модуль є JS-точкою входу правила `ga` для уніфікованих lint-pipelin-ів проєкту. Типові викликачі:
+
+- **Загальний lint-оркестратор** (наприклад, кореневий `bun run lint` або `npx @nitra/cursor lint`), який обходить активні правила й для кожного, що має JS-частину, викликає експортовану функцію `lint`. Передає список файлів (зі staged/змінених) — для правила `ga` цей список буде проігноровано.
+- **CI workflows** — через ту саму lint-команду, але з повним списком файлів репо або без нього.
+
+Те, що адаптер ігнорує `files`, — свідома архітектурна декларація: лінт `ga` не вміє швидко перевіряти одинокі workflow-файли, бо правила `ga.mdc` мають cross-file семантику (узгодженість назв джоб, повторювані workflows, спільний `workflow_common` тощо), плюс зовнішні інструменти (`actionlint`, `zizmor`) самі обходять директорію `.github/workflows/` цілком.
+
+### Звʼязок з канонічним CLI
+
+Існує **дві** окремі точки входу до лінтингу правила `ga`:
+
+1. `bin/n-cursor.js` → підкоманда `lint-ga` → `runLintGaCli` напряму (CLI-користувач, дзвонить руками або в скриптах).
+2. Загальний lint pipeline → `npm/rules/ga/js/lint.mjs::lint(files)` → `runLintGaCli` (програмний шлях для обхідника правил).
+
+Обидві дороги ведуть у одну й ту саму функцію `runLintGaCli`, що гарантує ідентичну поведінку, exit code і побічні ефекти незалежно від точки входу.
+
+### Контракт повернення
+
+- Викликач має право трактувати результат як стандартний POSIX exit code: `0` — лінт пройшов, інше — є порушення або інфраструктурна помилка (наприклад, відсутній `uv` без можливості auto-install).
+- Адаптер не нормалізує код помилки й не маскує його — якщо `runLintGaCli` повернув `2`, `lint` поверне `2`.
+
+### Обмеження та крайні випадки
+
+- **Per-file режиму немає.** Передача `files` нічого не змінює; для оптимізації CI краще запускати правило `ga` тільки коли реально змінилися файли в `.github/workflows/` (це — рішення викликача, а не адаптера).
+- **Жодного захисту від конкурентного запуску** на рівні цього адаптера: серіалізація важких CLI-команд (по конвенції `scripts.mdc`) реалізована всередині `runLintGaCli` через `runStandardLint`.
+- **Жодного preflight тут не виконується** — увесь preflight (ensureTool для `shellcheck`/`conftest`, перевірка `uv`) живе всередині `runLintGaCli`.

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

@@ -0,0 +1,217 @@
+# workflows.mjs
+
+## Огляд
+
+Модуль `workflows.mjs` реалізує JS-частину перевірки правила **ga.mdc** (GitHub Actions) у пакеті `@nitra/cursor`. Він валідує конфігурацію `.github/workflows/` цільового репозиторію: розширення файлів (`.yml`, не `.yaml`), наявність обовʼязкових workflow, відсутність MegaLinter-залишків, коректність triggers `on.*.paths`, наявність composite-action `setup-bun-deps` і локальне встановлення `shellcheck`.
+
+Модуль працює в парі з **Rego-полісі** з `npm/policy/ga/`: пер-документні структурні перевірки (поля YAML, `concurrency`, заборона `oven-sh/setup-bun` / `actions/cache` / `bun install`, мінімальні версії `uses`, наявність `actions/checkout@v6` перед локальним `setup-bun-deps`, shell-продовження `\` у `run`) делеговані Rego і викликаються через `runConftestBatch`. У JS лишилися ті перевірки, які потребують доступу до файлової системи / git-індексу (`git ls-files :(glob)`, `existsSync`, читання `readdir`) і не можуть бути виражені declarative-полісі.
+
+Точка входу — асинхронна функція `check(cwd)`, яка повертає exit code (`0` — успіх, `1` — є проблеми). Її викликає `bun run lint-ga` разом з `actionlint` і `zizmor`.
+
+Plan B-патерн: rego-частина авторитетна для пер-документних правил; JS виконує cross-file і tooling-перевірки. Hard-fail якщо `conftest` відсутній у PATH (узгоджено з `runConftestBatch`).
+
+## Експорти / API
+
+| Експорт                                | Тип              | Призначення                                                                     |
+| -------------------------------------- | ---------------- | ------------------------------------------------------------------------------- |
+| `check(cwd?)`                          | `async function` | Головна точка входу: валідує `ga.mdc` для репозиторію `cwd`.                    |
+| `checkShellcheckInstalled(pass, fail)` | `function`       | Перевіряє наявність бінарника `shellcheck` у PATH (актуальне для `actionlint`). |
+
+Решта функцій модуля — приватні (module-local) хелпери, які не експортуються.
+
+## Функції
+
+### `gitHasAnyTrackedFileMatchingGlob(globPattern, cwd)`
+
+- **Сигнатура:** `(globPattern: string, cwd: string) => boolean`
+- **Параметри:**
+  - `globPattern` — glob із workflow (наприклад `files/**`, `image-migration-new/**`).
+  - `cwd` — робочий каталог для виклику `git`.
+- **Повертає:** `true`, якщо хоча б один tracked-файл у git-індексі матчить glob; `true` для негативних патернів (починаються з `!`); `false` — якщо patternstring порожній або `git` упав.
+- **Side effects:** спавн дочірнього процесу `git ls-files -z -- :(glob)<pattern>` через `execFileSync` (синхронно).
+- **Особливості:** використовує pathspec `:(glob)`, щоб делегувати glob-матчинг git-у, без ручної реалізації glob-engine і без рекурсивного сканування FS.
+
+### `shouldValidateWorkflowPathsGlob(p)`
+
+- **Сигнатура:** `(p: string) => boolean`
+- **Параметри:** `p` — рядковий glob із `on.*.paths`.
+- **Повертає:** `true`, якщо glob варто валідувати на існування файлів; `false` для негативних патернів (`!...`) та для патернів зі вставкою `*.` (типу `*.vue`, `*.php` — заготовки для майбутніх файлів).
+- **Side effects:** немає (чиста функція).
+
+### `verifyOnePathsGlob(relPath, eventName, raw, passFn, failFn, cwd)`
+
+- **Сигнатура:** `(relPath: string, eventName: string, raw: unknown, passFn: (msg: string) => void, failFn: (msg: string) => void, cwd: string) => void`
+- **Параметри:**
+  - `relPath` — відносний шлях workflow-файлу для повідомлень.
+  - `eventName` — назва події (`push` або `pull_request`).
+  - `raw` — сирий елемент із масиву `paths` (може бути будь-яким типом).
+  - `passFn`/`failFn` — колбеки звітування.
+  - `cwd` — корінь репозиторію для `git`.
+- **Повертає:** `void`.
+- **Side effects:** виклики `passFn` або `failFn` (запис у reporter).
+- **Поведінка:**
+  - Порожній/нерядковий glob — ігнорує.
+  - Glob, який не треба валідувати (`shouldValidateWorkflowPathsGlob === false`) — звітує `pass` з поясненням «пропущено для перевірки існування».
+  - Інакше викликає `gitHasAnyTrackedFileMatchingGlob` і звітує відповідно `pass` (є збіги) або `fail` (немає жодного).
+
+### `verifyWorkflowEventPathsGlobsExist(relPath, root, passFn, failFn, cwd)`
+
+- **Сигнатура:** `(relPath: string, root: Record<string, unknown>, passFn, failFn, cwd: string) => void`
+- **Параметри:** `root` — розпарсений YAML workflow.
+- **Повертає:** `void`.
+- **Side effects:** делеговано `verifyOnePathsGlob`.
+- **Логіка:** дістає `on.push.paths` та `on.pull_request.paths` через `getObjKey`, ітерує масивами і викликає `verifyOnePathsGlob` для кожного елемента. Якщо `on` відсутній, не є обʼєктом, або `paths` не є масивом — нічого не робить.
+
+### `getObjKey(obj, key)`
+
+- **Сигнатура:** `(obj: unknown, key: string) => unknown`
+- **Повертає:** значення поля `obj[key]`, якщо `obj` — non-array object; інакше `undefined`.
+- **Side effects:** немає.
+- **Призначення:** безпечний доступ до вкладеного поля YAML, де root може виявитись не-обʼєктом після парсингу.
+
+### `checkApplyWorkflow(wfDir, files, filename, expectedPath, passFn, failFn)`
+
+- **Сигнатура:** `async (wfDir: string, files: string[], filename: string, expectedPath: string, passFn, failFn) => Promise<void>`
+- **Параметри:**
+  - `wfDir` — абсолютна директорія `.github/workflows`.
+  - `files` — список файлів у `wfDir`.
+  - `filename` — імʼя apply-workflow (наприклад `apply-k8s.yml`).
+  - `expectedPath` — очікуваний шаблон у `on.push.paths` (наприклад `**/k8s/**/*.yaml`).
+- **Повертає:** `Promise<void>`.
+- **Side effects:** читає файл `wfDir/filename`, звітує через `passFn`/`failFn`.
+- **Логіка:** якщо `filename` відсутній у `files` — повертає без перевірки. Інакше парсить YAML через `parseWorkflowYaml`; перевірку наявності `expectedPath` у `on.push.paths` робить точно через `eventPathsIncludeExact`, а якщо YAML не розпарсився — fallback на наївний `content.includes`.
+
+### `checkMegalinter(wfDir, ymlWorkflows, wfDirRel, cwd, passFn, failFn)`
+
+- **Сигнатура:** `async (wfDir, ymlWorkflows: string[], wfDirRel, cwd, passFn, failFn) => Promise<void>`
+- **Повертає:** `Promise<void>`.
+- **Side effects:** читає всі `*.yml` у `wfDir`, перевіряє `existsSync` для кореневих конфіг-файлів.
+- **Що шукає:**
+  1. У вмісті кожного `.yml` workflow — патерни `MEGALINTER_USE_PATTERNS` (`oxsecurity/megalinter-action`, `megalinter/megalinter`).
+  2. У корені репо — файли з `MEGALINTER_CONFIG_NAMES` (`.mega-linter.yml`, `.megalinter.yaml`, `.mega-linter.yaml`).
+- Знайшов — `fail` з вимогою видалити інтеграцію; не знайшов — один `pass`.
+
+### `checkShellcheckInstalled(passFn, failFn)` _(export)_
+
+- **Сигнатура:** `(passFn, failFn) => void`
+- **Повертає:** `void`.
+- **Side effects:** `resolveCmd('shellcheck')` (`which`/`where`).
+- **Призначення:** `actionlint` (через `bunx github-actionlint`) перевіряє shell-код у `run:` блоках лише коли `shellcheck` доступний; інакше тихо пропускає SC-правила. Локальний `bun lint-ga` міг би бути зеленим, тоді як CI на `ubuntu-latest` (де `shellcheck` передвстановлений) падатиме. Тому відсутність бінарника локально — `fail` з порадами встановлення для macOS/Debian/Ubuntu/Arch.
+- **Крос-платформність:** через `resolveCmd` коректно знаходить `shellcheck` і `shellcheck.exe` на Windows.
+
+### `checkGaWorkflowFiles(wfDirRel, files, pass, fail)`
+
+- **Сигнатура:** `(wfDirRel: string, files: string[], pass, fail) => void`
+- **Повертає:** `void`.
+- **Side effects:** виклики `pass`/`fail`.
+- **Перевірки:**
+  - Файли з розширенням `.yaml` → `fail` (вимога перейменувати на `.yml`); якщо таких немає — один `pass` про відповідність розширень.
+  - Файли без розширення `.yml` → `fail`.
+  - Кожен з `REQUIRED_WORKFLOWS` (`clean-ga-workflows.yml`, `clean-merged-branch.yml`, `lint-ga.yml`, `git-ai.yml`) має існувати: є — `pass`, немає — `fail`.
+
+### `runAllGaRego(wfDir, ymlWorkflows, cwd, pass, fail)`
+
+- **Сигнатура:** `async (wfDir: string, ymlWorkflows: string[], cwd: string, pass, fail) => Promise<void>`
+- **Повертає:** `Promise<void>`.
+- **Side effects:** спавн `conftest` через `runConftestBatch`; читання шаблонів через `loadTemplate`.
+- **Логіка:**
+  1. **Per-workflow Rego (4 окремих спавни):** для кожного запису в `GA_PER_WORKFLOW_REGO_TARGETS` (4 канонічні workflow), якщо файл існує — підтягує `loadTemplate(concernDir)`, бере `templateData[basename(workflow)]` і викликає `runConftestBatch` з відповідним `policyDirRel`/`namespace`/одним файлом. Кожне порушення → `fail` з префіксом шляху; нуль порушень → один `pass` «відповідає `<namespace>` (rego)».
+  2. **Workflow-common батч:** один спавн `conftest` з полісі `ga/workflow_common` на ВСІ `*.yml` у `wfDir`. Шаблон `uses-min-versions.snippet` (якщо є) передається у `templateData`. Порушення → `fail` з префіксом filename; нуль — `pass` про кількість файлів, що відповідають `ga.workflow_common`.
+- **Чому 4 окремих спавни, а не один:** namespace ↔ конкретний workflow; інакше правила одного workflow застосуються до неправильного файла.
+
+### `check(cwd?)` _(export, точка входу)_
+
+- **Сигнатура:** `async (cwd?: string) => Promise<number>`
+- **Параметри:** `cwd` — корінь репозиторію (за замовчуванням `process.cwd()`).
+- **Повертає:** exit code: `0` — все OK, `1` — є порушення (отримується з `reporter.getExitCode()`).
+- **Side effects:** створення reporter, читання FS, виклики `git`, спавни `conftest`.
+- **Послідовність перевірок:**
+  1. Створює `reporter` через `createCheckReporter()`.
+  2. Перевіряє наявність директорії `.github/workflows` — якщо немає, негайно `fail` і повертає exit code.
+  3. Зчитує `files = readdir(wfDir)`; виокремлює `ymlWorkflows` (`*.yml`).
+  4. **Rego-крок** (`runAllGaRego`) — першим, як authoritative source для пер-документних правил.
+  5. Наявність `composite action` `.github/actions/setup-bun-deps/action.yml` (його розкочує `npx @nitra/cursor`).
+  6. `checkGaWorkflowFiles` — розширення і обовʼязкові workflow.
+  7. `checkApplyWorkflow` × 2 — `apply-k8s.yml` (`**/k8s/**/*.yaml`) і `apply-nats-consumer.yml` (`**/consumer.yaml`).
+  8. `checkMegalinter` — залишки інтеграції/конфіги.
+  9. Для кожного `*.yml` — парсить YAML і викликає `verifyWorkflowEventPathsGlobsExist` (git-залежна перевірка `on.*.paths`).
+  10. `checkShellcheckInstalled` — наявність бінарника локально.
+  11. Повертає `reporter.getExitCode()`.
+
+## Залежності
+
+### Node.js core
+
+- `node:fs` — `existsSync` (синхронна перевірка існування шляхів).
+- `node:fs/promises` — `readdir`, `readFile` (асинхронні).
+- `node:child_process` — `execFileSync` (для `git ls-files`).
+- `node:path` — `basename`, `dirname`, `join`.
+- `node:url` — `fileURLToPath` (резолв `import.meta.url` → шлях).
+
+### Внутрішні модулі (`@nitra/cursor`)
+
+- `../../../scripts/lib/check-reporter.mjs` → `createCheckReporter` — фабрика reporter з `pass`/`fail`/`getExitCode`.
+- `../../../scripts/lib/gha-workflow.mjs` → `eventPathsIncludeExact`, `parseWorkflowYaml` — YAML-парсер workflow і helper для перевірки точного шляху в `on.<event>.paths`.
+- `../../../scripts/utils/resolve-cmd.mjs` → `resolveCmd` — крос-платформний `which`/`where`.
+- `../../../scripts/lib/run-conftest-batch.mjs` → `runConftestBatch` — батч-обгортка над `conftest` (hard-fail без `conftest` у PATH).
+- `../../../scripts/lib/template.mjs` → `loadTemplate` — підтягує `template.json`-снипети з директорій Rego-полісі.
+
+### Зовнішні бінарники (runtime)
+
+- `git` — для `git ls-files -z -- :(glob)<pattern>`.
+- `conftest` — викликається через `runConftestBatch` (hard-fail без нього).
+- `shellcheck` — перевіряється на наявність у PATH (інформаційно).
+
+### Дані конфігурації
+
+- `MEGALINTER_USE_PATTERNS` — regexp-патерни для пошуку MegaLinter у workflow.
+- `MEGALINTER_CONFIG_NAMES` — імена конфіг-файлів MegaLinter у корені.
+- `REQUIRED_WORKFLOWS` — 4 обовʼязкових workflow з ga.mdc.
+- `GA_PER_WORKFLOW_REGO_TARGETS` — мапінг `workflow → namespace → policyDirRel` для пер-документного rego.
+- `GA_POLICY_DIR` — обчислюється як `dirname(import.meta.url)/../policy` → абсолютний шлях до `npm/rules/ga/policy/`.
+- `HERE` — `dirname(fileURLToPath(import.meta.url))` (директорія самого `workflows.mjs`).
+
+## Потік виконання / Використання
+
+### Виклик з лінт-пайплайну
+
+Модуль викликається непрямо через CLI `@nitra/cursor` як частина правила ga (роутер у `npm/rules/ga/`). Цільовий репозиторій запускає `bun run lint-ga`, який також виконує `actionlint` і `zizmor` поза цією функцією, але `check()` цього модуля — інтегрована частина того ж run.
+
+### Програмний виклик
+
+```js
+import { check } from '@nitra/cursor/rules/ga/js/workflows.mjs'
+
+const exitCode = await check(process.cwd())
+process.exit(exitCode)
+```
+
+### Послідовність на рівні `check()`
+
+1. `createCheckReporter()` створює пару колбеків `pass`/`fail` і лічильник exit code.
+2. Перевірка наявності `.github/workflows/` — early return при відсутності.
+3. `readdir` всіх файлів у директорії, фільтрація `*.yml`.
+4. **Rego-фаза:** 4 окремих `conftest` для канонічних workflow + 1 батч `ga.workflow_common` на всі `*.yml`. Усі порушення → `fail` через reporter.
+5. **JS-фаза cross-file:**
+   - Перевірка `.github/actions/setup-bun-deps/action.yml`.
+   - Розширення (`yaml→yml`) і набір обовʼязкових workflow.
+   - `apply-k8s.yml` / `apply-nats-consumer.yml` — точна перевірка `paths` через AST.
+   - MegaLinter-залишки (workflow + конфіги).
+   - Кожен workflow → парс YAML → перевірка `on.*.paths` через `git ls-files :(glob)`.
+   - `shellcheck` у PATH.
+6. Повертає `reporter.getExitCode()` (`0` або `1`).
+
+### Інтерпретація результатів
+
+- Кожен виклик `pass(msg)` додає ОК-рядок у reporter.
+- Кожен виклик `fail(msg)` додає помилку і встановлює exit code = 1.
+- Звіт виводиться форматтером `check-reporter.mjs` (поза цим модулем).
+
+### Розширення модуля
+
+Нові пер-документні перевірки workflow слід додавати в Rego-полісі (`npm/policy/ga/<concern>/`) — не сюди. Тут — лише ті перевірки, які потребують FS/git/external-tool доступу. Якщо додаєш новий канонічний workflow:
+
+1. Додай у `REQUIRED_WORKFLOWS`.
+2. Створи новий пакет у `npm/policy/ga/<name>/` з Rego-правилами.
+3. Зареєструй у `GA_PER_WORKFLOW_REGO_TARGETS` (`workflow`/`namespace`/`policyDirRel`).
+4. За потреби — додай `apply-...` стилю trigger-перевірку через `checkApplyWorkflow`.