# lint.mjs

## Огляд

Файл `npm/rules/rego/js/lint.mjs` — це тонкий ESM-адаптер, що виконує роль CI-кроку (`lint`) для правила `rego` в монорепо. Він не містить власної логіки перевірки чи парсингу, а лише делегує виклик у вже існуючий CLI-модуль правила — `../lint/lint.mjs`. Файл існує задля відповідності уніфікованому контракту CI-кроків (`lint(files?)`), де очікується експорт функції `lint` з певною сигнатурою.

Ключова особливість: режим перевірки **per-file** для правила `rego` не підтримується — аналіз завжди виконується на всьому репозиторії (whole-repo). Тому параметр `files`, який зазвичай передається CI-фреймворком у крок `lint`, тут навмисно ігнорується (на що вказує префікс `_` у назві аргументу — `_files`). Це маркер для лінтерів та читачів коду, що значення параметра не використовується.

Файл є частиною інфраструктури правил (`.cursor/rules/n-rego.mdc`, `.cursor/rules/n-ci4.mdc`) і служить мостом між уніфікованою CI-сигнатурою кроків та конкретною реалізацією перевірки Rego-файлів.

## Експорти / API

Файл експортує одну іменовану асинхронну функцію:

| Експорт | Тип                                                 | Призначення                                          |
| ------- | --------------------------------------------------- | ---------------------------------------------------- |
| `lint`  | `async function(files?: string[]): Promise<number>` | CI-крок для лінтингу Rego-файлів; повертає exit code |

Default-експорт відсутній. Експорт іменований, що відповідає конвенції CI-кроків у проєкті (де runner імпортує саме `{ lint }`).

## Функції

### `lint(_files)`

#### Сигнатура

```js
export async function lint(_files)
```

#### Параметри

| Параметр | Тип                     | Обов'язковий | Опис                                                                                                                                                                               |
| -------- | ----------------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `_files` | `string[] \| undefined` | ні           | Список файлів для перевірки. **Ігнорується** — `rego`-лінтер не має per-file режиму та виконує whole-repo аналіз. Префікс `_` сигналізує, що параметр свідомо не використовується. |

#### Повертає

`Promise<number>` — exit code від `runLintRego()`:

- `0` — лінтинг пройшов без помилок;
- ненульове значення — виявлено порушення або стався збій під час перевірки.

Конкретні значення коду визначає реалізація `runLintRego` у `../lint/lint.mjs` — цей файл лише транслює його далі.

#### Side effects

Сама функція `lint` не має прямих побічних ефектів — вона не пише у файлову систему, не звертається до мережі, не модифікує глобальний стан і не виводить нічого у консоль. Усі побічні ефекти (виклики `opa`/`regal`, читання Rego-файлів, друк діагностики, можливі тимчасові файли тощо) реалізовані всередині `runLintRego` із сусіднього модуля `../lint/lint.mjs` та повністю інкапсульовані там.

#### Винятки

Функція не має власних `try`/`catch`. Якщо `runLintRego()` відхилить проміс (`reject`) або викине синхронну помилку, виняток прозоро прокинеться вгору до викликача (зазвичай — CI-runner, який очікує саме на exit code).

## Залежності

### Внутрішні (relative)

| Імпорт        | Шлях               | Призначення                                                                                                                         |
| ------------- | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------- |
| `runLintRego` | `../lint/lint.mjs` | Реалізація whole-repo лінтингу Rego-файлів — фактично виконує перевірку та повертає exit code. Цей файл є єдиною залежністю модуля. |

### Зовнішні

Зовнішніх npm-залежностей файл напряму не використовує. Усі сторонні інструменти (наприклад, `opa`, `regal` тощо) транзитивно підключаються через `runLintRego`.

### Runtime

ESM-модуль (`.mjs`), потребує Node.js / Bun з підтримкою native ESM та `async/await`.

## Потік виконання / Використання

### Послідовність дій

1. CI-runner (наприклад, фреймворк CI-кроків `n-ci4`) виявляє файл як крок `lint` правила `rego`.
2. Runner викликає `lint(files)` — передає або список змінених файлів, або `undefined`, залежно від режиму запуску.
3. Функція ігнорує аргумент `_files` і одразу викликає `runLintRego()` без параметрів.
4. `runLintRego()` повертає `Promise<number>` із exit code; `lint` повертає цей самий проміс (через `return` в `async`-функції — фактично awaits та віддає значення).
5. Runner отримує exit code і інтерпретує його як результат CI-кроку.

### Контрактна позиція в системі правил

Файл реалізує уніфікований інтерфейс CI-кроку `lint(files?)`, очікуваний фреймворком правил репозиторію (`n-ci4`). Завдяки тонкому шару адаптації:

- сам runner може бути неуважним до особливостей правила (per-file vs whole-repo);
- логіка перевірки залишається інкапсульованою у `../lint/lint.mjs` і може використовуватися як з CI, так і з CLI напряму;
- зміна реалізації `runLintRego` не вимагає правок цього файла.

### Приклад використання

```js
import { lint } from './npm/rules/rego/js/lint.mjs'

// CI-режим: список файлів є, але буде проігнорований
const exitCode = await lint(['policy/a.rego', 'policy/b.rego'])
process.exit(exitCode)

// Або без аргументів — поведінка ідентична
const code2 = await lint()
process.exit(code2)
```

### Що НЕ робить цей файл

- Не парсить аргументи командного рядка — це не CLI-entrypoint.
- Не фільтрує файли за розширенням — фільтрація (за потреби) — справа `runLintRego`.
- Не агрегує помилки кількох інструментів — повертає лише підсумковий exit code.
- Не пише у `stdout`/`stderr` — увесь вивід походить із `runLintRego`.

## Rebuild Test

Документація достатня, щоб переписати файл з нуля без перегляду оригіналу:

- Модуль ESM (`.mjs`).
- Імпорт: `runLintRego` із `../lint/lint.mjs`.
- Один іменований експорт — `async function lint(_files)`.
- Тіло: `return runLintRego()` (виклик без аргументів).
- JSDoc: параметр `_files` — `string[] | undefined`, описаний як ігнорований (whole-repo аналіз); повертає `Promise<number>` (exit code).
- Коментар верхнього рівня: пояснює, що це CI-крок `rego`, делегує у CLI правила, per-file режиму немає, `files` ігнорується.
