@nitra/cursor 3.25.1 → 3.27.0

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/lint/docs/lint.md

@@ -1,209 +1,27 @@
-# `npm/rules/ga/lint/lint.mjs`
+# lint.mjs
 
 ## Огляд
 
-Модуль `lint.mjs` — це **CLI-обгортка над канонічним `lint-ga`** (правило `ga.mdc`), яка виконує комплексну перевірку GitHub Actions workflow-файлів проєкту. Модуль не є самостійним перевіряльником: він агрегує кілька стадій external-tools і делегує JS/Rego-частину перевірок в `rules/ga/fix.mjs::check()`.
-
-Ключові зони відповідальності:
-
-1. **Авто-встановлення обов'язкових бінарників** — `shellcheck` і `conftest` через `ensureTool` (підбирається менеджер пакетів per-platform: `brew`/`scoop`/GitHub Release).
-2. **Preflight для `uv`** — м'яка перевірка, що `uv` (а отже `uvx`) є в `PATH`; інакше друкується hint з командами встановлення й функція повертає `1` без авто-install.
-3. **Послідовний запуск трьох стадій перевірки** workflow-ів:
-   - `bunx github-actionlint` — синтаксис/семантика GH Actions, включно з вбудованим `shellcheck` у `run:` блоках (звідси preflight на `shellcheck`).
-   - `uvx zizmor --offline --collect=workflows .` — second-stage security-аудит workflow на ризики (через `uv`/`uvx`).
-   - `rules/ga/fix.mjs::check()` — Rego-полісі (батч `conftest` для `npm/policy/ga/`) **плюс** JS cross-file перевірки правил `ga.mdc`. Це та сама перевірка, що й `npx @nitra/cursor check ga`, тож `lint-ga` є суперсетом цієї підкоманди.
-4. **Серіалізація запуску** через `runStandardLint(import.meta.dirname, steps)` згідно з каноном патерну `lint-*` (див. `.cursor/rules/scripts.mdc`, секція «Серіалізація важких CLI-команд») — без прямого `withLock`.
-
-Plan B-патерн (rego-authoritative): сама Rego-полісі `npm/policy/ga/` запускає `rules/ga/fix.mjs::check()` як перший крок — `lint.mjs` про це не знає. Раніше `lint.mjs` сам спавнив `conftest` per-workflow для `ga.<name>` і `ga.workflow_common` (PoC); тепер уся логіка централізована в `rules/ga/fix.mjs`, тому одне джерело істини без дублювання між `lint-ga` і `npx @nitra/cursor check ga`.
-
-Чому preflight на `shellcheck` обов'язковий: без нього `bunx github-actionlint` **мовчки** пропускає shell-перевірки у `run:` блоках; локально `bun lint-ga` лишається зеленим, а CI на `ubuntu-latest` (де `shellcheck` передвстановлений) падає. `ensureTool('shellcheck')` усуває цю різницю.
-
-Чому `uv` — окремо й лише як hint: бінарник `uv` не входить у реєстр `ensureTool` для авто-install у цьому проєкті, тому модуль обмежується інформативною підказкою з командами встановлення (brew / curl / pip), щоб користувач не отримав неінформативну помилку від `uvx zizmor`.
-
-Модуль експортує одну іменовану стрілкову функцію `runLintGaCli`, яку імпортує `bin/n-cursor.js` як обробник підкоманди `lint-ga`.
-
-## Експорти / API
-
-| Символ         | Тип                             | Експорт                | Опис                                                                                                                                                                   |
-| -------------- | ------------------------------- | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `runLintGaCli` | `() => Promise<number>` (arrow) | `export const` (named) | Точка входу CLI-команди `lint-ga`. Обгортає `runLintGaSteps` у `runStandardLint(import.meta.dirname, ...)` — серіалізація + стандартні timing/exit-code/log конвенції. |
-
-Жодних інших експортів модуль не надає: усі допоміжні функції (`resolvePreflightBin`, `printPreflightMissingMessage`, `preflight`, `runLintGaSteps`) і константа `UV_PREFLIGHT` — внутрішні.
-
-JSDoc-typedef `PreflightDep` описує форму внутрішніх preflight-конфігів і не експортується.
-
-## Функції
-
-### `resolvePreflightBin(dep)`
-
-```
-function resolvePreflightBin(dep: PreflightDep): string | null
-```
-
-- **Параметри:**
-  - `dep: PreflightDep` — опис preflight-залежності з полями `bin`, `winBins`, `explanation`, `install`, `successMsg`.
-- **Повертає:** `string | null` — абсолютний шлях до бінарника або `null`, якщо нічого не знайдено в `PATH`.
-- **Поведінка:**
-  - Якщо `platform === 'win32'` (з `node:process`), спершу ітерує `dep.winBins` (наприклад, `['uv.exe']`) і повертає перший резолвлений шлях.
-  - Якщо жоден `winBins` не знайдено або платформа не Windows — фолбек на `resolveCmd(dep.bin)`.
-- **Side effects:** немає (читання `PATH` через `resolveCmd` — pure-resolve).
-
-### `printPreflightMissingMessage(dep)`
-
-```
-function printPreflightMissingMessage(dep: PreflightDep): void
-```
-
-- **Параметри:** `dep: PreflightDep`.
-- **Повертає:** `void`.
-- **Поведінка:** друкує у `stderr` блок із кількох рядків:
-  1. `❌ <bin> не знайдено в PATH.` (червоний хрестик у вигляді емодзі).
-  2. Пояснення з `dep.explanation` (одинарний відступ на 3 пробіли).
-  3. Заголовок `Встанови:` і список команд із `dep.install` з відступом на 5 пробілів.
-  4. Фінальний рядок-вказівка: `Деталі: ga.mdc → секція про lint-ga.`
-- **Side effects:** запис у `process.stderr` через `console.error`. Жодних винятків не кидає.
-
-### `preflight(dep)`
-
-```
-function preflight(dep: PreflightDep): boolean
-```
-
-- **Параметри:** `dep: PreflightDep`.
-- **Повертає:** `boolean` — `true`, якщо бінарник знайдено в `PATH`; `false`, якщо ні.
-- **Поведінка:**
-  - Викликає `resolvePreflightBin(dep)`.
-  - На pass: друкує `dep.successMsg` через `console.log` і повертає `true`.
-  - На fail: викликає `printPreflightMissingMessage(dep)` і повертає `false`.
-- **Side effects:** запис у `stdout` (success) або `stderr` (fail) через `console.log`/`console.error`.
-
-### `runLintGaSteps()`
-
-```
-async function runLintGaSteps(): Promise<number>
-```
-
-- **Параметри:** немає.
-- **Повертає:** `Promise<number>` — `0`, якщо всі кроки успішні; інакше — exit-code першого кроку, що впав.
-- **Поведінка (послідовно):**
-  1. `ensureTool('shellcheck')` — авто-install або hard-fail (кидає виняток, який підхоплює `runStandardLint` і конвертує в `exit 1`).
-  2. `ensureTool('conftest')` — те саме.
-  3. `preflight(UV_PREFLIGHT)` — якщо `uv` не знайдено, повертає `1` без падіння (hint-only).
-  4. `runLintStep('actionlint', 'bunx', ['github-actionlint'])` → якщо код ≠ 0, повертає його.
-  5. `runLintStep('zizmor', 'uvx', ['zizmor', '--offline', '--collect=workflows', '.'])` → якщо код ≠ 0, повертає його.
-  6. Друкує заголовок `▶ check-ga (rego-полісі npm/policy/ga/ + JS cross-file перевірки)` і повертає `await checkGa()` (з `../js/workflows.mjs`).
-- **Side effects:**
-  - Можлива інсталяція пакетів через `ensureTool` (мутує систему: brew/scoop/завантаження бінарників).
-  - Спавн процесів `bunx`, `uvx` через `runLintStep`.
-  - Виклик `conftest` (батчем) і JS-перевірки всередині `checkGa()`.
-  - Запис у `stdout`/`stderr`.
-
-### `runLintGaCli` (експортовано)
-
-```
-export const runLintGaCli: () => Promise<number>
-```
-
-- **Параметри:** немає.
-- **Повертає:** `Promise<number>` — результат `runStandardLint(...)`, тобто фінальний exit-code лінт-команди.
-- **Поведінка:** обгортає `runLintGaSteps` у `runStandardLint(import.meta.dirname, runLintGaSteps)`. `import.meta.dirname` визначає каталог `npm/rules/ga/lint/`, що використовується для лок-файлу серіалізації та для службових логів.
-- **Side effects:** успадковуються від `runStandardLint` (lock-файл / cleanup) і `runLintGaSteps`.
-
-## Внутрішні дані
-
-### `UV_PREFLIGHT`
-
-```
-const UV_PREFLIGHT: PreflightDep
-```
-
-Конфігурація preflight для `uv`:
-
-- `bin: 'uv'`
-- `winBins: ['uv.exe']`
-- `explanation`: двохрядкове пояснення про те, що без `uv`/`uvx` не запуститься `uvx zizmor` (second-stage аудит workflow на ризики GitHub Actions).
-- `install`:
-  - `'macOS:        brew install uv'`
-  - `'Universal:    curl -LsSf https://astral.sh/uv/install.sh | sh'`
-  - `'pip:          pip install uv'`
-- `successMsg: '✅ uv знайдено в PATH — uvx zizmor запуститься'`
-
-### `PreflightDep` (JSDoc typedef)
-
-Структура опису однієї preflight-залежності:
-
-| Поле          | Тип        | Опис                                                                                           |
-| ------------- | ---------- | ---------------------------------------------------------------------------------------------- |
-| `bin`         | `string`   | Базове ім'я виконуваного файлу (на Windows додається `.exe` за потреби — через `winBins`).     |
-| `winBins`     | `string[]` | Альтернативні імена на Windows (наприклад, `shellcheck.exe`); якщо порожньо — фолбек на `bin`. |
-| `explanation` | `string`   | 1–2 рядки, що пояснюють наслідки відсутності бінарника.                                        |
-| `install`     | `string[]` | Список рядків з командами встановлення (друкуються «як є», з відступом).                       |
-| `successMsg`  | `string`   | Повідомлення, яке друкується на pass-шлях preflight-у.                                         |
-
-## Залежності
-
-### Зовнішні (Node.js core)
-
-- `node:process` — імпортується `platform` (рядок типу `'darwin' | 'linux' | 'win32' | ...`) для гілки Windows у `resolvePreflightBin`.
-
-### Внутрішні (проєктні)
-
-- `../js/workflows.mjs` — імпорт `check as checkGa`. Виконує Rego-полісі (батч `conftest` для `npm/policy/ga/`) і JS cross-file перевірки правил `ga.mdc`. Це фінальний крок `runLintGaSteps`.
-- `../../../scripts/utils/resolve-cmd.mjs` — `resolveCmd(name): string | null`. Pure-resolve бінарника у `PATH` (без спавну).
-- `../../../scripts/lib/run-lint-step.mjs` — `runLintStep(label, cmd, args): number`. Стандартизований обгортковий спавн одного кроку lint-у з консистентним логом і exit-code-семантикою.
-- `../../../scripts/lib/run-standard-lint.mjs` — `runStandardLint(dirname, fn): Promise<number>`. Канонічна серіалізація lint-команди (lock-файл, тривалість, sentry-style cleanup). Згідно з `.cursor/rules/scripts.mdc` (секція «Серіалізація важких CLI-команд»), цей хелпер заміняє прямий `withLock` у lint-обгортках.
-- `../../../scripts/lib/ensure-tool.mjs` — `ensureTool(name): void`. Перевіряє наявність бінарника в `PATH` і автоматично встановлює його через відповідний менеджер пакетів per-platform (brew/scoop/GitHub Release). Кидає виняток на нездатність встановити.
-
-### Зовнішні CLI-інструменти (запускаються в рантаймі)
-
-- `shellcheck` — авто-install через `ensureTool`. Потрібен для shell-перевірок у `run:` блоках, які виконує `actionlint`.
-- `conftest` — авто-install через `ensureTool`. Використовується **всередині** `checkGa()` для виконання Rego-полісі з `npm/policy/ga/`.
-- `uv` / `uvx` — hint-only preflight. Потрібен для запуску `uvx zizmor`.
-- `bunx` / `github-actionlint` — виконується через `runLintStep('actionlint', 'bunx', ['github-actionlint'])`.
-- `uvx` / `zizmor` — виконується через `runLintStep('zizmor', 'uvx', ['zizmor', '--offline', '--collect=workflows', '.'])`.
-
-## Потік виконання / Використання
-
-### Інтеграція в CLI
-
-Модуль експортує `runLintGaCli`, яку імпортує `bin/n-cursor.js` як обробник підкоманди:
-
-```
-npx @nitra/cursor lint-ga
-# або
-bun lint-ga
-```
-
-### Сценарій типового запуску (happy path)
-
-1. `runLintGaCli()` → викликає `runStandardLint(import.meta.dirname, runLintGaSteps)` — отримується lock на `npm/rules/ga/lint/`, починається timing.
-2. Усередині `runLintGaSteps`:
-   - `ensureTool('shellcheck')` — якщо нема, авто-встановлення (brew/scoop/release).
-   - `ensureTool('conftest')` — те саме.
-   - `preflight(UV_PREFLIGHT)` — друкує `✅ uv знайдено в PATH — uvx zizmor запуститься`.
-   - `runLintStep('actionlint', 'bunx', ['github-actionlint'])` — exit `0`.
-   - `runLintStep('zizmor', 'uvx', ['zizmor', '--offline', '--collect=workflows', '.'])` — exit `0`.
-   - Лог `▶ check-ga (rego-полісі npm/policy/ga/ + JS cross-file перевірки)`.
-   - `await checkGa()` — повертає `0`.
-3. `runStandardLint` логує загальну тривалість, знімає lock і повертає `0`.
-
-### Сценарії з falure
-
-- `shellcheck` або `conftest` не встановлено й `ensureTool` не зміг встановити — виняток пробивається крізь `runLintGaSteps`, `runStandardLint` ловить його та конвертує у `exit 1`.
-- `uv` відсутній — `preflight(UV_PREFLIGHT)` друкує hint, `runLintGaSteps` повертає `1`, наступні кроки не виконуються.
-- `actionlint` повертає не-нульовий код — `runLintGaSteps` повертає цей код, `zizmor` і `checkGa()` не запускаються.
-- `zizmor` повертає не-нульовий код — те саме: одразу повертається його exit-code.
-- `checkGa()` повертає не-нульовий код — він і є фінальним результатом `runLintGaCli`.
-
-### Контракт «суперсет `check ga`»
-
-Оскільки фінальний крок `runLintGaSteps` — `checkGa()` (та сама `check`-функція з `../js/workflows.mjs`, що використовується підкомандою `npx @nitra/cursor check ga`), `lint-ga` є суперсетом цієї перевірки: він додає `actionlint` (синтаксис) і `zizmor` (security-аудит) перед `check`. Це усуває потребу запускати `check ga` окремо в pipeline-ах, що вже виконують `lint-ga`.
-
-### Канон патерну `lint-*`
-
-Файл сповідує канон патерну `lint-*` із `.cursor/rules/scripts.mdc` (секція «Серіалізація важких CLI-команд»):
-
-- Серіалізація — через `runStandardLint`, **не** через прямий `withLock`.
-- Кожна стадія — через `runLintStep` (узгоджений лог-формат, semantic exit-codes).
-- Експортована функція має назву `run<Name>Cli` (тут — `runLintGaCli`).
-- Фінальна делегація бізнес-частини — у відповідний `rules/<name>/fix.mjs::check()`, щоб бути одним джерелом істини з `npx @nitra/cursor check <name>`.
+Файл надає CLI-обгортку для інструменту `lint-ga`, який автоматично встановлює необхідні інструменти, такі як `shellcheck` та `conftest`, для перевірки коду. Він послідовно виконує перевірку коду за допомогою Rego та JavaScript, забезпечуючи узгодженість з правилами `ga.mdc`.  Цей файл служить централізованим джерелом для виконання та налаштування процесу linting, що спрощує інтеграцію в CI/CD.
+
+## Поведінка
+
+1.  **Підготовка середовища:** Перевіряє наявність необхідних інструментів: `shellcheck` та `conftest`. Якщо їх немає, автоматично встановлює їх, щоб забезпечити коректну роботу.
+2.  **Перевірка залежностей:** Перевіряє наявність `uv`. Якщо `uv` відсутній, надає інструкції щодо його встановлення, щоб забезпечити виконання наступного етапу.
+3.  **Запуск попередньої перевірки:** Виконує попередню перевірку за допомогою `github-actionlint`, що дозволяє виявити проблеми на ранніх етапах.
+4.  **Виконання аналізу коду:** Запускає `uvx zizmor` для поглибленого аналізу коду, включаючи перевірку на відповідність стандартам та виявлення потенційних проблем.
+5.  **Перевірка Rego-полісів:** Запускає Rego-полісі з `npm/policy/ga/` для забезпечення відповідності коду політикам.
+6.  **Перевірка правил:** Виконує перевірку правил `ga.mdc` як для JS-коду, так і для Rego-полісів, забезпечуючи загальну відповідність стандартам.
+7.  **Звіт про результати:** Формує звіт про результати перевірки, що включає інформацію про виявлені проблеми та їх серйозність.
+8.  **Повернення статусу:** Повертає код завершення, що вказує на успішне виконання або наявність проблем, які потребують уваги.
+
+## Гарантії поведінки
+
+*   `ensureTool` встановлює `shellcheck` та `conftest` згідно з обраним методом встановлення (brew, scoop, GitHub Release).
+*   Якщо `uv` не встановлено, `uvx zizmor` завершується з помилкою.
+*   `bunx github-actionlint` пропускає shell-перевірки в `run:` блоках, якщо `shellcheck` не вказаний у PATH.
+*   `runLintGaCli` повертає `false` або `null` при помилках, не викликаючи виняток.
+*   Не використовується кешування.
+*   `uvx zizmor` вимагає наявності `uv`.
+*   Логіка встановлення та запуску перевірок централізована у `rules/ga/fix.mjs`.
+*   `runLintGaCli` використовується як підкоманда `lint-ga`.