@nitra/cursor 3.26.0 → 3.28.0

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

@@ -1,100 +1,19 @@
-# `npm/rules/ga/js/lint.mjs`
+# lint.mjs
 
 ## Огляд
 
-Файл `lint.mjs` у теці `npm/rules/ga/js/` є тонкою адаптерною ланкою (CI-кроком) правила `ga` (GitHub Actions). Він не реалізує жодної самостійної логіки лінтингу — натомість делегує виклик у канонічну CLI-обгортку правила, яка живе у сусідньому модулі `npm/rules/ga/lint/lint.mjs` (експортує `runLintGaCli`).
+Файл `lint` делегує перевірку коду інструменту, який запускається з командного рядка. Він використовується для автоматизованої перевірки коду на відповідність певним правилам. Це забезпечує консистентність та якість коду в проєкті.
 
-Призначення модуля — надати уніфікований lint-entry для правила `ga`, який відповідає інтерфейсному контракту «JS-частини правила» (експорт `async function lint(files)`), і одночасно явно зафіксувати, що правило `ga` працює **тільки в whole-repo режимі**: per-file-аналіз не підтримується, а вхідний аргумент `files` ігнорується.
+## Поведінка
 
-Контекст:
+1.  Запускає наявний CLI для перевірки правил.
+2.  Проводить аналіз всього репозиторію, ігноруючи вказаний список файлів.
+3.  Повертає код завершення процесу.
+4.  Не використовує кеш результатів.
+5.  Не здійснює взаємодії з мережею.
 
-- Правило `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`.
+- Делегує правила до існуючого CLI.
+- Не враховує `files` в режимі per-file.
+- Не має кешування.

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

@@ -2,216 +2,31 @@
 
 ## Огляд
 
-Модуль `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`.
+Файл перевіряє GitHub Actions workflows на відповідність певним правилам та стандартам. Він забезпечує консистентність та якість workflow, виявляючи потенційні проблеми, такі як відсутність clean/lint workflow або використання непідтримуваних інструментів. Це частина автоматизованого процесу забезпечення дотримання найкращих практик при розробці GitHub Actions.
+
+## Поведінка
+
+- `checkShellcheckInstalled`: Перевіряє наявність бінарника `shellcheck` в системному PATH.
+- `checkGaWorkflowFiles`: Перевіряє наявність workflow-файлів з розширенням `.yml` та відсутність інших розширень.
+- `runAllGaRego`: Запускає Rego-перевірки для всіх workflow-файлів, використовуючи `conftest` для аналізу.
+- `check`: Координує всі перевірки, включаючи Rego-аналіз, перевірку workflow-структури та перевірку наявність файлів.
+
+## Публічний API
+
+- checkShellcheckInstalled — Перевіряє наявність `shellcheck` у системі та зупиняє workflow, якщо його немає.
+- check — Перевіряє відповідність проєкту правилам валідації.
+- runAllGaRego — Запускає Rego-перевірку правил, як перший етап валідації.
+- lint-ga — Запускає перевірку `bun lint-ga` з використанням `actionlint` та `zizmor`.
+
+## Гарантії поведінки
+
+- Гарантується наявність файлів `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.

package/rules/ga/js/workflows.mjs

@@ -1,19 +1,4 @@
-/**
- * Перевіряє GitHub Actions за правилом ga.mdc.
- *
- * Workflows лише з розширенням `.yml`, наявність clean/lint workflow,
- * відсутність MegaLinter, виклик у `lint-ga.yml`,
- * наявність composite `.github/actions/setup-bun-deps/action.yml` (його записує npx `\@nitra/cursor`),
- *
- * Структурні поля 4 канонічних workflow (`clean-ga-workflows.yml`, `clean-merged-branch.yml`,
- * `lint-ga.yml`, `git-ai.yml`) і УНІВЕРСАЛЬНІ перевірки для всіх `.github/workflows/*.yml`
- * (`concurrency`, заборонені `oven-sh/setup-bun` / `actions/cache` / `bun install` у `uses`/`run`,
- * shell-продовження `\` у `run`, обов'язковий `actions/checkout@v6` перед локальним
- * `setup-bun-deps`), а також `package.json`, `.vscode/*` і `.github/zizmor.yml` —
- * у Rego-полісі під `npm/policy/ga/`. Тут лишилися FS/git/tooling перевірки:
- * наявність файлів, MegaLinter leftovers, `on.*.paths` через `git ls-files :(glob)`,
- * і локальний `shellcheck`.
- */
+/** @see ./docs/workflows.md */
 import { existsSync } from 'node:fs'
 import { readdir, readFile } from 'node:fs/promises'
 import { execFileSync } from 'node:child_process'