@nitra/cursor 3.26.0 → 3.28.0

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`.

package/rules/graphql/js/tooling.mjs

@@ -1,12 +1,4 @@
-/**
- * Перевіряє правило graphql.mdc: наявність **`.graphqlrc.yml`** і рекомендації
- * **`graphql.vscode-graphql`**, якщо у дереві є **`gql\`…\``**.
- *
- * Обхід репозиторію — **`walkDir`** від **`process.cwd()`** (пропуски як у інших check). Кандидати — **`.vue`** та **`.js`/`.ts`/`.jsx`/`.tsx`** тощо; пропуск **`.d.ts`**, **auto-imports.d.ts** тощо — **`shouldSkipFileForGqlScan`**.
- *
- * Виявлення **`gql`** — **oxc-parser** після витягування `<script>` з SFC (**`graphql-gql-scan.mjs`**). Якщо збігів немає — перевірка завершується успішно без вимог до конфігів.
- * @param {string} cwd корінь репозиторію
- */
+/** @see ./docs/tooling.md */
 import { existsSync } from 'node:fs'
 import { readFile } from 'node:fs/promises'
 import { join, relative } from 'node:path'

package/rules/hasura/js/internal_urls.mjs

@@ -1,27 +1,4 @@
-/**
- * Перевіряє правило hasura.mdc для проєктів **nitra** і **abie**: значення
- * `HASURA_GRAPHQL_ENDPOINT` у `*.env` має бути **внутрішнім** кластерним URL,
- * а не публічним доменом.
- *
- * Запускається лише якщо в кореневому `package.json` поле `repository`
- * вказує на `https://github.com/nitra/...` або `https://github.com/abinbevefes/...`
- * (інші репозиторії пропускаються без помилок — як у abie-перевірках).
- *
- * Очікуваний формат URL — кластерний DNS-суфікс `<cluster>.internal`:
- *  - GKE / GCP: `http://<service>.<namespace>.svc.<cluster>.internal:<port>`
- *    приклад: `http://contract-h-hl.ua-contract.svc.abie-ua.internal:8080`
- *
- * Сегменти беруться з `hasura/k8s/base/svc-hl.yaml` (`metadata.name` —
- * headless, має закінчуватись на `-h-hl`; див. `hasura.svc_hl` / k8s.svc_hl_yaml) і
- * `hasura/k8s/base/namespace.yaml`
- * (`metadata.name` — namespace). Якщо ці YAML є в репозиторії, у URL додатково
- * звіряються конкретні `<service>` і `<namespace>` з ними.
- *
- * Скануються всі файли `*.env` (наприклад `dev.env`, `production.env`); файл
- * `.env` без імені — виключення з правила (локальний файл розробника), його
- * не перевіряємо. Пропускаються `node_modules`, `.git`, `dist`, `coverage`,
- * `.turbo`, `.next` (як у `walkDir`).
- */
+/** @see ./docs/internal_urls.md */
 import { existsSync } from 'node:fs'
 import { readFile } from 'node:fs/promises'
 import { basename, join, relative } from 'node:path'

package/rules/image-avif/js/avif_generation.mjs

@@ -1,30 +1,4 @@
-/**
- * Перевіряє відповідність репозиторію правилу `image-avif.mdc`: AVIF-генерацію та
- * ув'язування `.avif`-двійників з посиланнями у `.vue`/`.html`.
- *
- * Дії під час `check image-avif`:
- * 1. **Pre-scan**: знайти в `.vue`/`.html` хоча б одне raster-посилання, яке потенційно
- *    можна переписати на AVIF-двійник (через `import x from '...png'` або
- *    `<img src="...png" />`). Пакети з opt-out `disable-avif: true` пропускаються.
- *    Якщо жодного raster-посилання не знайдено → exit 0 одразу (`npx --avif` не запускаємо,
- *    rewrite/cleanup-пасс теж пропускаємо — нічого не змінилось би).
- * 2. `npx \@nitra/minify-image --src=. --write --avif` — генерує AVIF-двійники.
- * 3. У кожному workspace-пакеті переписує raster-посилання у `.vue`/`.html` на `.avif`
- *    (де AVIF-двійник реально існує на диску). Pakety з `"\@nitra/minify-image": {
- *    "disable-avif": true }` у `package.json` пропускаються.
- * 4. Прибирає AVIF-сироти — `<name>.<ext>.avif`, на які не лишилось жодного посилання
- *    у `.vue`/`.html` репозиторію, видаляються (умова правила: «AVIF лишається лише
- *    там, де заміна вдалася»).
- *
- * Якщо raster-посилання у `.vue`/`.html` не вдалось переписати (наприклад, оригіналу
- * нема на диску → `.avif` теж не згенерувався) — фейл на конкретний файл.
- *
- * Правило самостійне від `image-compress`: AVIF можна вмикати лише в адмінках (де AVIF
- * підтримується сучасними браузерами) і не вмикати в публічних сайтах. Перевірка скрипта
- * `lint-image` (заборона `--avif` у ньому) залишається у `image-compress` — тут вона не
- * дублюється.
- * @param {string} cwd корінь репозиторію
- */
+/** @see ./docs/avif_generation.md */
 import { existsSync } from 'node:fs'
 import { readFile, unlink, writeFile } from 'node:fs/promises'
 import { join, relative } from 'node:path'

package/rules/image-compress/js/package_setup.mjs

@@ -1,21 +1,4 @@
-/**
- * Перевіряє вимоги правила `image-compress.mdc` для оптимізації raster/SVG через
- * `@nitra/minify-image` ≥ 3.2.0 (локально).
- *
- * **Що тут лишилося** (FS / cross-file):
- *  - наявність `package.json` у корені;
- *  - `.n-minify-image.tsv` (committed source of truth з sha1/originalSize/size) НЕ
- *    в `.gitignore` — він має бути в git;
- *  - застарілий `.minify-image-cache.tsv` (з версій < 3.2) видалений з кореня та
- *    з `.gitignore`.
- *
- * **Що покрила Rego** (`npx \@nitra/cursor fix`,
- * `npm/rules/image-compress/policy/package_json/`):
- *  - `scripts.lint-image` викликає `npx \@nitra/minify-image --src=. --write`
- *    без `--avif` (AVIF — окреме правило `image-avif`);
- *  - агрегований `lint` (якщо є) містить `bun run lint-image`;
- *  - `@nitra/minify-image` НЕ у `dependencies` / `devDependencies` (через `npx`).
- */
+/** @see ./docs/package_setup.md */
 import { existsSync } from 'node:fs'
 import { readFile } from 'node:fs/promises'
 import { join } from 'node:path'

package/rules/js-bun-db/js/safety.mjs

@@ -1,34 +1,4 @@
-/**
- * Перевіряє правило js-bun-db.mdc.
- *
- * 1) У жодному `package.json` (включно з workspace-пакетами) у `dependencies` не повинно
- *    бути `pg-format` чи `mysql2` — їх треба замінити на Bun native SQL
- *    (`import { sql, SQL } from 'bun'`, https://bun.com/docs/runtime/sql). `pg-format` —
- *    ручне форматування SQL через escape; tagged template Bun SQL параметризує значення
- *    нативно і не лишає простору для injection. Перевірка цих двох — у Rego-полісі
- *    `npm/policy/js_bun_db/package_json/`.
- *
- * 2) Для `pg` діє виключення: Bun SQL поки не реалізує LISTEN/NOTIFY, тож якщо у
- *    проекті знайдено реальне використання `LISTEN ...` / `NOTIFY ...` / `UNLISTEN ...`
- *    або listener'а `.on('notification', ...)`, dependency `pg` дозволено. Інакше
- *    `pg` лишається забороненим — fail з підказкою про виключення. Додатково — per-file:
- *    кожен файл з `import ... from 'pg'` повинен сам містити LISTEN/NOTIFY-патерн;
- *    звичайні SELECT/INSERT/UPDATE через `pg` (replace на Bun SQL!) не дозволені.
- *
- * 3) Якщо в коді використовується Bun SQL (імпорт `sql`/`SQL` з `'bun'`), додатково
- *    перевіряє небезпечні патерни:
- *    - `new SQL(...)` всередині функції (пул має бути singleton на рівні модуля).
- *    - Будь-який `<obj>.unsafe(...)` без маркера-коментаря `// allow-unsafe: <reason>`
- *      на тому ж рядку або рядком вище. `sql.unsafe` за замовчуванням заборонено;
- *      допустимий лише для підстановки назви таблиці/колонки чи dynamic SQL/DDL,
- *      коли значення контролюється кодом (не user input) — в інших випадках
- *      переробляємо на tagged template `sql\`...\${value}...\``.
- *    - pg-leftover виклики `<obj>.connect(...)` / `<obj>.end(...)` у файлах, що
- *      імпортують Bun SQL: пулом керує Bun, життєвий цикл вручну не потрібен.
- *      Opt-out — маркер `// allow-pg-leftover: <reason>`.
- *    - Динамічні SQL-списки через `.join(',')` у `IN (...)` / `VALUES (...)`
- *      (треба `sql([...])`).
- */
+/** @see ./docs/safety.md */
 import { existsSync } from 'node:fs'
 import { readFile } from 'node:fs/promises'
 import { join, relative } from 'node:path'

package/rules/js-bun-redis/js/imports.mjs

@@ -1,15 +1,4 @@
-/**
- * Перевіряє правило `js-bun-redis.mdc`.
- *
- * Заборонено в JS/TS-джерелах будь-який `import` / `require` / динамічний `import()` пакетів
- * `ioredis`, `node-redis`, `redis` (та підпакетів `@redis/*`, підшляхів `ioredis/...` /
- * `redis/...`). Замість них треба використовувати Bun native Redis:
- * `import { redis } from 'bun'` (<https://bun.com/docs/runtime/redis>).
- *
- * Перевірку `dependencies` (заборона `ioredis` / `node-redis` / `redis` / `@redis/*` у будь-якому
- * `package.json`) винесено в Rego-полісі `npm/policy/js_bun_redis/package_json/`; її запускає
- * `npx \@nitra/cursor check`. Тут лишився AST-скан коду через `oxc-parser`.
- */
+/** @see ./docs/imports.md */
 import { existsSync } from 'node:fs'
 import { readFile } from 'node:fs/promises'
 import { join, relative } from 'node:path'

package/rules/js-lint/js/docs/lint-findings.md

@@ -0,0 +1,30 @@
+# lint-findings.mjs
+
+## Огляд
+
+Цей файл обробляє результати аналізу коду, отримані з інструментів oXlint та eslint, для визначення, чи є знайдені проблеми нові (в diff) чи існують у файлі з самого початку. Він класифікує ці результати, надаючи інформацію про файл та рядок, де проблема виявлена, що допомагає у відстеженні та вирішенні помилок. Це частина системи беклогу #6, яка автоматизує процес класифікації lint-findings.
+
+## Поведінка
+
+parseOxlint: аналізує JSON-вихід `oxlint --format=json` та повертає список findings з інформацією про файл, рядок, правило та повідомлення.
+parseEslint: аналізує JSON-вихід `eslint --format=json` та повертає список findings з інформацією про файл, рядок, правило та повідомлення.
+classifyFindings: класифікує findings як introduced або pre-existing на основі доданих рядків, використовуючи Map.
+renderFindings: генерує текстовий звіт з розділенням findings на introduced та pre-existing, використовуючи формат `🆕 introduced` та `🗄 pre-existing`.
+
+## Публічний API
+
+- parseOxlint — Перетворює JSON з результатів інструменту Oxlint на внутрішній об'єкт.
+- parseEslint — Перетворює JSON з результатів інструменту ESLint на внутрішній об'єкт.
+- classifyFindings — Розподіляє знайдені проблеми на нові (introduced) та існуючі (pre-existing).
+- renderFindings — Створює звіт, об'єднуючи нові та існуючі проблеми.
+
+## Гарантії поведінки
+
+- Функція `parseOxlint` повертає JSON-об'єкт, що містить список діагностик, або `null` у разі помилки парсингу.
+- Функція `parseEslint` повертає масив об'єктів, що містять повідомлення про помилки, або `null` у разі помилки парсингу.
+- Функція `classifyFindings` повертає масив об'єктів, що представляють класифіковані результати, або `null` у разі помилки класифікації.
+- Функція `renderFindings` повертає рядок, що містить представлення результатів, або `null` у разі помилки рендерингу.
+- У разі невдачі будь-якої з функцій, повертається `false`.
+- Функції не кидають винятків.
+- Шляхи файлів, що передаються вхідним функціям, є абсолютними.
+- Результати функцій не кешуються.

package/rules/js-lint/js/lint-findings.mjs

@@ -1,10 +1,4 @@
-/**
- * Нормалізація й класифікація lint-findings (oxlint + eslint) на introduced
- * (рядок у diff від HEAD) vs pre-existing (борг файлу) — беклог #6, варіант A.
- *
- * Формати: oxlint `--format=json` → `{ diagnostics:[{ filename, code, labels:[{span:{line}}] }] }`;
- * eslint `--format=json` → `[{ filePath, messages:[{ ruleId, line, message }] }]`. Шляхи абсолютні.
- */
+/** @see ./docs/lint-findings.md */
 import { isAbsolute, relative } from 'node:path'
 
 import { isIntroducedLine } from '../../../scripts/lib/diff-added-lines.mjs'

package/rules/js-lint/js/lint.mjs

@@ -1,13 +1,4 @@
-/**
- * Quick-крок lint правила js-lint: oxlint + eslint (з автофіксом).
- *
- * Викликається lint-оркестратором (`n-cursor lint` / `lint-ci`):
- *  - `files` = масив змінених файлів (quick) → лінтимо лише js-подібні з них і
- *    КЛАСИФІКУЄМО лишені findings на introduced (рядок у diff від HEAD) vs
- *    pre-existing (борг файлу) — беклог #6, варіант A (видимість; блокування без змін);
- *  - `files` = undefined (ci) → лінтимо весь проєкт (стрімінг, без класифікації).
- * Крос-файлові jscpd/knip — окреме правило js-lint-ci (фаза ci).
- */
+/** @see ./docs/lint.md */
 import { spawnSync } from 'node:child_process'
 
 import { addedLinesByFile } from '../../../scripts/lib/diff-added-lines.mjs'

package/rules/js-lint/js/tooling.mjs

@@ -1,16 +1,4 @@
-/**
- * Перевіряє лінт JavaScript за правилом js-lint.mdc.
- *
- * Flat ESLint з getConfig і ignore для auto-imports,
- * `.oxlintrc.json` має збігатися з каноном oxlint у пакеті (`npm/rules/js-lint/js/data/tooling/oxlint-canonical.json`):
- * plugins, jsPlugins, categories, усі правила з канону (додаткові записи в `rules` дозволені), settings, env,
- * globals, ignorePatterns. Також перевіряє workspace `package.json` на `type: "module"`
- * і `engines`, workflow-дубль у `lint.yml`, `knip.json` autofill і застарілі `.eslintrc*`.
- *
- * Per-document вимоги (`lint-js`, `@nitra/eslint-config`, root `engines`, `.jscpd.json`,
- * `.vscode/extensions.json`, `lint-js.yml`) — у policy-пакетах `js_lint.*`.
- * @param {string} cwd корінь репозиторію
- */
+/** @see ./docs/tooling.md */
 import { existsSync } from 'node:fs'
 import { copyFile, readFile } from 'node:fs/promises'
 import { dirname, join } from 'node:path'

package/rules/js-lint/js/utils_imports.mjs

@@ -1,21 +1,4 @@
-/**
- * Перевіряє, що файли всередині будь-якого `utils/` каталогу не мають імпортів за межі
- * самого каталогу (relative-import з `..`). За правилом `js-lint.mdc` каталог `utils/` — це
- * generic helpers без бізнес-логіки і без залежностей від домену; якщо файлу потрібен
- * сусідній модуль, конфіг проєкту чи cross-rule helper — він має жити в `lib/`, а не в `utils/`.
- *
- * Перевіряються лише не-тестові `.mjs|.mts|.cjs|.cts|.js|.ts|.jsx|.tsx` під будь-яким
- * `utils/`-каталогом у monorepo-воркспейсах. Файли всередині `utils/tests/` (тести)
- * і будь-які `__fixtures__/` ігноруються — тести легально імпортують свій модуль через `../X`.
- *
- * Дозволені імпорти:
- *  - `./X`, `./sub/X` — same-dir чи глибше всередині самої `utils/`
- *  - bare-package (`oxc-parser`, `@scope/pkg`) — npm-залежність
- *  - `node:fs`, `fs` тощо — Node-builtin
- *
- * Заборонено:
- *  - будь-який `..`-шлях (`../X`, `../../X`) — це порушення granular `utils/`-кордону
- */
+/** @see ./docs/utils_imports.md */
 import { readdir, readFile } from 'node:fs/promises'
 import { join, relative, sep } from 'node:path'
 

package/rules/js-lint-ci/js/lint.mjs

@@ -1,9 +1,4 @@
-/**
- * Ci-крок: jscpd (детектор клонів) + knip (невикористані експорти).
- *
- * Крос-файлові аналізатори — працюють лише по всьому репо, тож `files` ігнорується
- * (викликається лише у `lint-ci` з undefined). Per-file режиму ці інструменти не мають.
- */
+/** @see ./docs/lint.md */
 import { spawnSync } from 'node:child_process'
 
 /**

package/rules/js-mssql/js/deps.mjs

@@ -1,13 +1,4 @@
-/**
- * Перевіряє правило js-mssql.mdc.
- *
- * Якщо в будь-якому `package.json` у репозиторії (включно з workspace-пакетами) в секції `dependencies`
- * присутній пакет `mssql`, його версія має бути не менше 12.5.0.
- *
- * Додатково, якщо `mssql` використовується в репозиторії, перевіряє що підключення
- * не створюється “на кожен запит”: `new sql.ConnectionPool(...)` не має знаходитись
- * всередині функцій. Пул має бути singleton (на рівні модуля) і повторно використовуватись.
- */
+/** @see ./docs/deps.md */
 import { existsSync } from 'node:fs'
 import { readFile } from 'node:fs/promises'
 import { join, relative } from 'node:path'

package/rules/js-run/js/runtime.mjs

@@ -1,40 +1,4 @@
-/**
- * Для кожного workspace-пакета перевіряє правило js-run.mdc.
- *
- * Покрито:
- *  - заборона `@nitra/bunyan` / `bunyan` як у залежностях `package.json`, так і в коді
- *    (`import` / `require` / динамічний `import()`); імпорти сканує AST через `oxc-parser`
- *    (див. `utils/bunyan-imports.mjs`);
- *  - наявність `OTEL_RESOURCE_ATTRIBUTES` зі значеннями `service.name=` та `service.namespace=`
- *    у `k8s/base/configmap.yaml`, якщо такий файл існує (відповідність імені ConfigMap імені
- *    Deployment перевіряється в `rules/k8s/fix.mjs`);
- *  - «Внутрішні аліаси» (`#conn/*`): імпорти `bun#SQL`, будь-який `mssql`, `@nitra/graphql-request#GraphQLClient`
- *    дозволені лише у каталозі conn (за замовчуванням `src/conn/`; за наявності
- *    `package.json#imports['#conn/*']` — у його цільовому каталозі); поза ним — порушення
- *    (див. `utils/conn-imports-scan.mjs`);
- *  - «Нейминг та експорти у `#conn/`»: всередині conn-каталогу basename файла має відповідати
- *    канону `ql-<id>` / `(pg|mysql|mssql)-(read|write)[-<id>]`; `export default` заборонений; має бути
- *    іменований експорт з імʼям, що дорівнює camelCase від basename файла (`pg-write-contract.js`
- *    → `export const pgWriteContract`); `index.*` як reexport-барель пропускаємо
- *    (див. `utils/conn-file-rules.mjs`);
- *  - «process.env / CheckEnv»: пряме `process.env.X` має бути замінено на `env` —
- *    з `@nitra/check-env` (для обов'язкових змінних, із `checkEnv([...])`) або з
- *    `node:process` (для опційних). Коли `env` імпортовано з `@nitra/check-env`,
- *    кожен `env.X` має бути закритий літеральним викликом `checkEnv(['X', ...])`
- *    у тому ж файлі або коментарем `// \@nitra/cursor ignore-next-line checkEnv`
- *    на попередньому рядку (див. `utils/check-env-scan.mjs`);
- *  - «Паузи через setTimeout»: `new Promise(resolve => setTimeout(resolve, ms))` (з/без `await`)
- *    треба замінити на `await setTimeout(ms)` з `node:timers/promises`
- *    (див. `utils/promise-settimeout-scan.mjs`);
- *  - «Temporal у Bun runtime»: identifier `Temporal` заборонений, бо поточний Bun runtime
- *    не має глобального Temporal API (див. `utils/temporal-scan.mjs`);
- *  - «jsconfig.json»: у backend-пакеті з каталогом `src/` у корені має бути `jsconfig.json`,
- *    вміст якого збігається з каноном js-run.mdc (NodeNext і include на дерево `src`).
- *
- * Per-document валідація `package.json` (bunyan, `node` у `scripts`) делегована rego-пакету
- * `js_run.package_json` у `npm/rules/js-run/policy/package_json/`; JS — cross-file (AST, FS).
- * @param {string} cwd корінь репозиторію
- */
+/** @see ./docs/runtime.md */
 import { existsSync, statSync } from 'node:fs'
 import { readFile } from 'node:fs/promises'
 import { join, relative } from 'node:path'

package/rules/js-run/lib/docs/temporal-scan.md

@@ -0,0 +1,25 @@
+# temporal-scan.mjs
+
+## Огляд
+
+Цей файл є частиною системи, яка сканує код Bun workspace на наявність використання ключового слова `Temporal`. Він запобігає використанню `Temporal` у backend-коді, оскільки Bun 1.3.x ще не має глобального `Temporal`, та охоплює сценарії з імпортом та polyfill. Це забезпечує відповідність коду поточним вимогам Bun runtime щодо обробки часу.
+
+## Поведінка
+
+Знаходить використання identifier `Temporal` у тексті. Повертає список рядків та фрагментів коду, де зустрічається `Temporal`.
+Чи сканувати файл за розширенням (JS/TS-сім'я, виключно з `.d.ts`). Повертає `true`, якщо файл має відповідне розширення, і не є файлом `.d.ts`.
+
+## Публічний API
+
+- findTemporalUsageInText — Знаходить згадки про `Temporal` у тексті.
+- isTemporalScanSourceFile — Визначає, чи потрібно сканувати файл за розширенням (JavaScript/TypeScript або `.d.ts`).
+
+## Гарантії поведінки
+
+- Функція `findTemporalUsageInText` повертає `true` лише якщо знайде identifier `Temporal` у наданому тексті.
+- Функція `findTemporalUsageInText` повертає `false` якщо identifier `Temporal` не знайдено.
+- Функція `isTemporalScanSourceFile` повертає `true` якщо у файлі є identifier `Temporal`.
+- Функція `isTemporalScanSourceFile` повертає `false` якщо у файлі немає identifier `Temporal`.
+- Результат роботи `findTemporalUsageInText` не гарантує, що identifier `Temporal` використовується правильно.
+- Результат роботи `isTemporalScanSourceFile` не гарантує, що використання `Temporal` є допустимим.
+- Кеш не використовується.