@nitra/cursor 5.1.0 → 5.2.1

package/rules/graphql/js/docs/tooling.md

@@ -1,264 +1,29 @@
-# tooling.mjs
-
-## Огляд
-
-Модуль `npm/rules/graphql/js/tooling.mjs` — це **check-скрипт правила `graphql.mdc`**, який перевіряє, що репозиторій налаштований для роботи з GraphQL за наявності у коді tagged template literals `gql\`...\``.
-
-Логіка перевірки **умовна**:
-
-1. Скрипт рекурсивно обходить дерево проєкту з кореня (`process.cwd()` за замовчуванням) і збирає файли-кандидати (`.vue`, `.js`, `.ts`, `.jsx`, `.tsx` тощо) — пропускаючи службові артефакти типу `.d.ts`, `auto-imports.d.ts` тощо.
-2. Для кожного кандидата виконує AST-сканування (oxc-parser; для `.vue` — після витягування блоку `<script>`) у пошуках `gql` tagged template literal.
-3. Якщо **жодного збігу не знайдено** — перевірка завершується успішно й нічого більше не вимагає.
-4. Якщо `gql\`…\`` **знайдено хоча б в одному файлі** — модуль вимагає:
-   - наявність файлу `.graphqlrc.yml` у корені репозиторію (GraphQL Config);
-   - відповідність `.vscode/extensions.json` rego-пакету `graphql.vscode_extensions` (тобто рекомендацію розширення VS Code `graphql.vscode-graphql`).
-
-Модуль є частиною інфраструктури `n-cursor` для перевірок правил `.mdc` і дотримується контракту check-скрипта: повертає exit code `0` при успіху й `1` при порушенні.
-
-## Експорти / API
-
-| Експорт                             | Тип                                        | Призначення                                                                             |
-| ----------------------------------- | ------------------------------------------ | --------------------------------------------------------------------------------------- |
-| `GRAPHQL_RC_FILENAME`               | `string` (const, `.graphqlrc.yml`)         | Очікувана назва файлу GraphQL Config у корені проєкту (з `graphql.mdc`).                |
-| `REQUIRED_GRAPHQL_VSCODE_EXTENSION` | `string` (const, `graphql.vscode-graphql`) | Ідентифікатор обов'язкового розширення VS Code, яке має бути в `recommendations`.       |
-| `check(cwd?)`                       | `async function`                           | Основна точка входу — виконує всю перевірку правила `graphql.mdc` і повертає exit code. |
-
-Внутрішні (не експортовані) хелпери:
-
-- `collectScanCandidates(root, ignorePaths)` — збір абсолютних шляхів файлів для сканування.
-- `collectGqlHits(root, candidates)` — фільтрація кандидатів за наявністю `gql` tagged template.
-- `checkExtensionsRecommendation(pass, fail, cwd)` — делегування перевірки `.vscode/extensions.json` rego-пакету `graphql.vscode_extensions` через `conftest`.
-
-## Функції
-
-### `collectScanCandidates(root, ignorePaths)`
-
-**Сигнатура:**
-
-```js
-async function collectScanCandidates(root: string, ignorePaths: string[]): Promise<string[]>
-```
-
-**Параметри:**
-
-- `root` — абсолютний шлях до кореня репозиторію, з якого починається обхід.
-- `ignorePaths` — масив абсолютних шляхів каталогів, які повністю виключаються з обходу (формується через `loadCursorIgnorePaths`).
-
-**Що робить:**
-
-- Викликає `walkDir(root, visitor, ignorePaths)` (рекурсивний обхід файлової системи).
-- Для кожного відвіданого файлу обчислює відносний шлях від `root`, нормалізує роздільники (Windows `\` → POSIX `/`).
-- Застосовує два фільтри:
-  - `shouldSkipFileForGqlScan(rel)` — пропуск службових файлів (`.d.ts`, `auto-imports.d.ts` тощо).
-  - `isGqlScanSourceFile(rel)` — допуск лише відповідних розширень (Vue/JS/TS-сімейство).
-- Накопичує **абсолютні** шляхи прийнятих файлів у масив `candidates`.
-
-**Повертає:** `Promise<string[]>` — список абсолютних шляхів файлів-кандидатів.
-
-**Side effects:** читає метадані файлової системи (через `walkDir`); записів не робить.
-
 ---
-
-### `collectGqlHits(root, candidates)`
-
-**Сигнатура:**
-
-```js
-async function collectGqlHits(root: string, candidates: string[]): Promise<string[]>
-```
-
-**Параметри:**
-
-- `root` — абсолютний шлях до кореня (для обчислення відносних шляхів у результаті).
-- `candidates` — список абсолютних шляхів файлів, отриманих від `collectScanCandidates`.
-
-**Що робить:**
-
-- Послідовно (`for-of` + `await`) для кожного абсолютного шляху:
-  - обчислює відносний шлях і нормалізує роздільники до `/`;
-  - читає вміст файлу через `readFile(absPath, 'utf8')`;
-  - викликає `sourceFileHasGqlTaggedTemplate(content, rel)` — парсер AST oxc, що враховує особливості `.vue` (витягування `<script>`);
-  - якщо результат `true` — додає **відносний** шлях до результуючого масиву `hits`.
-
-**Повертає:** `Promise<string[]>` — відносні шляхи файлів, у яких знайдено хоча б одне `gql` tagged template.
-
-**Side effects:** читання вмісту файлів з диска. Запис відсутній.
-
+docgen:
+  source: npm/rules/graphql/js/tooling.mjs
+  crc: eb6b4713
+  score: 100
 ---
 
-### `checkExtensionsRecommendation(pass, fail, cwd)`
-
-**Сигнатура:**
-
-```js
-function checkExtensionsRecommendation(
-  pass: (msg: string) => void,
-  fail: (msg: string) => void,
-  cwd: string
-): void
-```
-
-**Параметри:**
-
-- `pass` — функція-репортер «успішно» (отримана з `createCheckReporter()`).
-- `fail` — функція-репортер «порушення».
-- `cwd` — абсолютний корінь репозиторію.
-
-**Що робить:**
-
-1. Формує відносний (`.vscode/extensions.json`) і абсолютний шляхи до файлу VS Code-конфігу.
-2. Якщо файл **не існує** (`existsSync`) — викликає `fail(...)` з повідомленням про те, що треба створити файл і додати `graphql.vscode-graphql` у `recommendations`, посилаючись на `graphql.mdc`. Виходить.
-3. Інакше викликає `runConftestBatch({ policyDirRel: 'graphql/vscode_extensions', namespace: 'graphql.vscode_extensions', files: [pathAbs] })` — делегує перевірку rego-пакету conftest-у.
-4. Якщо `violations.length === 0` — викликає `pass(...)` з повідомленням про відповідність. Інакше — для кожного порушення `v` викликає `fail(v.message)`.
-
-**Повертає:** нічого (`void`). Результати фіксуються через `pass` / `fail`.
-
-**Side effects:**
-
-- читання `.vscode/extensions.json` через зовнішній conftest-процес;
-- виклик `conftest` (binary) усередині `runConftestBatch`;
-- зміна стану внутрішнього reporter-у (накопичення успіхів/порушень).
-
-**Виклик умовний:** виконується лише після того, як основна функція `check` виявила `gql` у дереві.
-
----
-
-### `check(cwd = process.cwd())`
-
-**Сигнатура:**
-
-```js
-export async function check(cwd?: string): Promise<number>
-```
-
-**Параметри:**
-
-- `cwd` — _необов'язковий_ абсолютний шлях до кореня репозиторію. За замовчуванням `process.cwd()`.
-
-**Що робить (потік):**
-
-1. Створює репортер `createCheckReporter()` і деструктурує з нього `pass`, `fail`.
-2. Завантажує список ігнорованих шляхів через `loadCursorIgnorePaths(root)`.
-3. Викликає `collectScanCandidates(root, ignorePaths)` — отримує список файлів-кандидатів.
-4. Викликає `collectGqlHits(root, candidates)` — отримує файли з `gql`.
-5. **Розгалуження:**
-   - Якщо `hits.length === 0` — викликає `pass(...)` з повідомленням «немає `gql\`…\``у джерелах, переглянуто N файлів —`.graphqlrc.yml`не вимагається» і **повертає**`reporter.getExitCode()`(зазвичай`0`).
-   - Інакше викликає `pass(...)` зі звітом про N файлів (з перших 5 з суфіксом `…` якщо більше).
-6. Перевіряє наявність `GRAPHQL_RC_FILENAME` (`.graphqlrc.yml`) у корені через `existsSync`:
-   - Існує → `pass('.graphqlrc.yml існує')`.
-   - Не існує → `fail(...)` з вимогою додати GraphQL Config (з посиланням на `graphql.mdc`).
-7. Викликає `checkExtensionsRecommendation(pass, fail, root)` для перевірки `.vscode/extensions.json`.
-8. Повертає `reporter.getExitCode()`: `0` — усі перевірки пройдені, `1` — є хоча б одне порушення.
-
-**Повертає:** `Promise<number>` — exit code (`0` — OK, `1` — порушення).
-
-**Side effects:**
-
-- читання файлової системи (метадані + вміст файлів кандидатів);
-- читання `.cursor/...` ignore-конфігу;
-- читання `.vscode/extensions.json` (опосередковано через conftest);
-- запуск процесу `conftest` через `runConftestBatch`;
-- мутація стану внутрішнього reporter-у (накопичення pass/fail-повідомлень).
-
-## Залежності
-
-### Node.js builtins
-
-| Модуль             | Що використовується | Призначення                                                                  |
-| ------------------ | ------------------- | ---------------------------------------------------------------------------- |
-| `node:fs`          | `existsSync`        | Синхронна перевірка наявності `.graphqlrc.yml` та `.vscode/extensions.json`. |
-| `node:fs/promises` | `readFile`          | Асинхронне читання вмісту файлів-кандидатів.                                 |
-| `node:path`        | `join`, `relative`  | Збирання абсолютних шляхів і обчислення відносних шляхів від кореня.         |
-
-### Внутрішні модулі репозиторію
-
-- `../../../scripts/lib/check-reporter.mjs` — `createCheckReporter`: фабрика репортера зі стандартним інтерфейсом `pass` / `fail` / `getExitCode()`.
-- `../lib/graphql-gql-scan.mjs`:
-  - `isGqlScanSourceFile(rel)` — предикат «це source-файл, який потенційно містить `gql`» (за розширенням);
-  - `shouldSkipFileForGqlScan(rel)` — предикат «цей файл слід ігнорувати при скануванні» (`.d.ts`, `auto-imports.d.ts` тощо);
-  - `sourceFileHasGqlTaggedTemplate(content, rel)` — AST-перевірка на наявність `gql\`...\``(через oxc-parser; для`.vue`— після витягування`<script>`).
-- `../../../scripts/lib/load-cursor-config.mjs` — `loadCursorIgnorePaths(root)`: повертає абсолютні шляхи каталогів, повністю виключених з обходу (узгоджено з іншими check-скриптами).
-- `../../../scripts/lib/run-conftest-batch.mjs` — `runConftestBatch({ policyDirRel, namespace, files })`: запускає `conftest` з rego-пакетом і повертає масив `violations` (об'єкти з `.message`).
-- `../../../scripts/utils/walkDir.mjs` — `walkDir(root, visitor, ignorePaths)`: рекурсивний обхід файлової системи з підтримкою списку ігнорування.
-
-### Зовнішні артефакти (не імпортуються, але потрібні в runtime)
-
-- **`conftest`** як CLI-binary (запускається з `runConftestBatch`).
-- **Rego-політика** в `graphql/vscode_extensions` з namespace `graphql.vscode_extensions` (перевіряє `.vscode/extensions.json`).
-- **`.cursor/ignore`-конфіг** у корені (читається `loadCursorIgnorePaths`).
-- **`graphql.mdc`** — правило, яке цей check реалізує.
-
-## Потік виконання / Використання
-
-### Запуск як check
-
-Модуль використовується з єдиною експортованою функцією `check`:
-
-```js
-import { check } from 'npm/rules/graphql/js/tooling.mjs'
-
-const exitCode = await check() // або await check('/absolute/path/to/repo')
-process.exit(exitCode)
-```
-
-Типово викликається диспетчером check-скриптів інфраструктури `n-cursor` (наприклад, із `npm/scripts/...`), який отримує exit code й агрегує результати по всіх правилах `.mdc`.
+# tooling.mjs
 
-### Послідовність дій усередині `check`
+## Огляд
 
-```
-process.cwd() (або переданий cwd)
-        │
-        ▼
-createCheckReporter() ──► { pass, fail, getExitCode }
-        │
-        ▼
-loadCursorIgnorePaths(root) ──► ignorePaths
-        │
-        ▼
-collectScanCandidates(root, ignorePaths)
-        │   walkDir(root, visitor, ignorePaths)
-        │     filter: !shouldSkipFileForGqlScan && isGqlScanSourceFile
-        ▼
-candidates: string[]
-        │
-        ▼
-collectGqlHits(root, candidates)
-        │   for each: readFile + sourceFileHasGqlTaggedTemplate (oxc-parser AST)
-        ▼
-hits: string[]
-        │
-        ├── hits.length === 0 ──► pass("немає gql у джерелах") ──► return 0
-        │
-        └── hits.length > 0
-              │
-              ├── pass("Знайдено gql у N файлі(ах): ...")
-              │
-              ├── existsSync(.graphqlrc.yml)
-              │     ├── true  ──► pass(".graphqlrc.yml існує")
-              │     └── false ──► fail("Відсутній .graphqlrc.yml ...")
-              │
-              ├── checkExtensionsRecommendation(pass, fail, root)
-              │     ├── !existsSync(.vscode/extensions.json) ──► fail(...)
-              │     └── runConftestBatch(graphql/vscode_extensions)
-              │           ├── violations.length === 0 ──► pass(...)
-              │           └── for v of violations: fail(v.message)
-              │
-              └── return reporter.getExitCode() (0 або 1)
-```
+Визначає ім'я файлу конфігурації (`GRAPHQL_RC_FILENAME` = ".graphqlrc.yml") та обов'язкове розширення VS Code (`REQUIRED_GRAPHQL_VSCODE_EXTENSION` = "graphql.vscode-graphql"). Перевіряє наявність конфігурації в `extensions.json` (конфігурація, на яку спирається код) та підтверджує необхідність розширення для роботи з GraphQL (graphql.mdc).
 
-### Семантика повідомлень
+## Поведінка
 
-- `pass` — інформативне повідомлення про успішну перевірку (логнеться як OK, не впливає на exit code).
-- `fail` — повідомлення про порушення; навіть одне `fail` робить `getExitCode()` рівним `1`.
+GRAPHQL_RC_FILENAME: Повертає ім'я файлу конфігурації GraphQL.
+REQUIRED_GRAPHQL_VSCODE_EXTENSION: Повертає ім'я розширення VS Code, необхідне для GraphQL.
+check: Перевіряє наявність `gql` tagged template у джерелах. Якщо знайдено, вимагає наявності `.graphqlrc.yml` та валідує `.vscode/extensions.json` щодо `graphql.vscode-graphql` (graphql.mdc).
 
-### Чому перевірка умовна
+## Публічний API
 
-`graphql.mdc` вимагає `.graphqlrc.yml` і VS Code-розширення `graphql.vscode-graphql` **лише** для проєктів, де реально використовуються `gql` tagged template literals. У монорепо це дозволяє не «спамити» правилом workspace-и, що не торкаються GraphQL — check спочатку доводить релевантність (`hits.length > 0`), і лише потім вимагає інфраструктуру.
+GRAPHQL_RC_FILENAME — вказує на файл конфігурації GraphQL у корені проєкту (graphql.mdc).
+REQUIRED_GRAPHQL_VSCODE_EXTENSION — вимагає встановлення розширення `graphql.vscode-graphql` для роботи з graphql.mdc.
+check — перевіряє наявність файлу `.graphqlrc.yml` та розширення `graphql.vscode-graphql` при використанні тегів GraphQL.
 
-### Обмеження та особливості
+## Гарантії поведінки
 
-- Шляхи в `hits` та в попередженнях завжди **відносні** до `root`, з POSIX-роздільниками `/` (навіть на Windows).
-- Перші 5 файлів-збігів показуються у повідомленні `pass`; решта приховується за суфіксом `…`.
-- Якщо `gql` знайдено, але `.vscode/extensions.json` відсутній — це порушення, незалежне від rego-перевірки (тобто `fail` без виклику conftest).
-- `collectGqlHits` читає файли **послідовно** (без `Promise.all`) — це навмисно, щоб не перевантажувати I/O при великих репозиторіях.
-- Виявлення `gql` — на рівні AST (oxc-parser), а не регулярних виразів; рядкові збіги типу `// gql\`...\`` у коментарі не дають false-positive.
+- Read-only: файл не виконує операцій запису у файлову систему.
+- Не звертається до мережі.

package/rules/graphql/lib/docs/graphql-gql-scan.md

@@ -1,3 +1,9 @@
+---
+docgen:
+  source: npm/rules/graphql/lib/graphql-gql-scan.mjs
+  crc: e110f9dd
+---
+
 # graphql-gql-scan.mjs
 
 ## Огляд

package/rules/hasura/docs/fix.md

@@ -1,120 +1,27 @@
-# fix.mjs — entry-point правила `hasura`
+---
+docgen:
+  source: npm/rules/hasura/fix.mjs
+  crc: 12fc1644
+  score: 100
+---
 
-## Огляд
-
-Файл `npm/rules/hasura/fix.mjs` — тонкий entry-point для правила з ідентифікатором `hasura` у складі CLI-пакета `@nitra/cursor`. Виконує дві ролі одночасно:
-
-1. **Library mode** — експортує функцію `run(ctx)`, яка викликається з оркестратора CLI (наприклад, з `runRuleCli` або з агрегаторів типу `n-fix`), що дозволяє запускати правило в межах загального прогону всіх правил без породження окремого процесу.
-2. **Standalone mode** — якщо файл виконується безпосередньо (через `bun rules/<id>/fix.mjs` або `node rules/<id>/fix.mjs`), він виступає самостійним CLI-входом, повністю еквівалентним `npx @nitra/cursor fix hasura`: підвантажує config, застосовує whitelist, друкує summary та повертає процесний exit-code.
-
-Уся фактична логіка правила (послідовність кроків `applies → JS-concerns → policy → mdc-refs`) винесена в спільну реалізацію `runStandardRule` із бібліотечного шару `scripts/lib/`. Файл-обгортка несе лише прив'язку правила до власної директорії (через `import.meta.dirname`) та dispatch між двома режимами запуску.
-
-Відповідає конвенції двороль­ового `fix.mjs`, ухваленій для всіх «стандартних» правил у `npm/rules/*/`, тож має мінімальну поверхню коду й не містить специфіки `hasura`: тип правила, скоупи, перевірки та поліcі описуються деінде (`meta.json`, `hasura.mdc`, `js/`, `policy/`).
-
-## Експорти / API
-
-| Експорт | Тип                                      | Призначення                                                                                                                      |
-| ------- | ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
-| `run`   | `(ctx?: RuleContext) => Promise<number>` | Library-mode прогін правила в спільному CLI orchestration. Повертає `0` при відсутності порушень або `1` при наявності порушень. |
-
-Файл не має `default`-експорту й не експортує жодних інших символів.
-
-Поведінка при безпосередньому запуску файлу як скрипта — побічний ефект (top-level `await runRuleCli(...)` + `process.exit(...)`) і не є частиною програмного API.
-
-## Функції
-
-### `run(ctx)`
-
-Сигнатура: `export function run(ctx)`.
-
-- **Параметри:**
-  - `ctx` (`RuleContext`, опційний) — контекст прогону, що передається з оркестратора. Тип імпортовано (через JSDoc-tag `@param`) з `../../scripts/lib/run-standard-rule.mjs`. Очікувані поля контексту (за конвенцією `runStandardRule`) — спільні для всіх правил, серед них зокрема `walkCache` (кеш обходу файлової системи, щоб не повторювати walk між кількома правилами в одному прогоні). Якщо `ctx` не передано (`undefined`), `runStandardRule` сам ініціалізує мінімально необхідний контекст.
-- **Повертає:** `Promise<number>` — exit-code правила:
-  - `0` — застосовні файли пройшли всі етапи (`applies → JS-concerns → policy → mdc-refs`) без виявлених порушень.
-  - `1` — знайдено принаймні одне порушення (або зафіксована помилка валідації, що інтерпретується як failure).
-- **Side effects:**
-  - Делегує всю роботу `runStandardRule(import.meta.dirname, ctx)`, який, своєю чергою, читає файли правила (`meta.json`, `*.mdc`, `js/*.mjs`, `policy/*.rego`) із директорії, обходить цільові файли проєкту, друкує діагностичні повідомлення у stdout/stderr та повертає підсумкове число порушень. Сам `run` стану не модифікує.
-  - Прив'язує правило до своєї директорії саме через `import.meta.dirname`, тож при переміщенні файлу `fix.mjs` правило автоматично «переїде» разом із його артефактами (без хардкоду шляхів).
-
-### Безіменна процедура top-level (standalone-блок)
+# fix.mjs
 
-```js
-if (isRunAsCli(import.meta.url)) {
-  process.exit(await runRuleCli(import.meta.dirname))
-}
-```
-
-- **Тип:** виконується один раз під час завантаження модуля.
-- **Параметри:** немає (CLI-аргументи зчитуються всередині `runRuleCli` через `process.argv`).
-- **Повертає:** нічого (виконує `process.exit`).
-- **Side effects:**
-  - `isRunAsCli(import.meta.url)` визначає, чи модуль завантажено як прямий entry-point (а не як `import`).
-  - У випадку прямого запуску викликає `runRuleCli(import.meta.dirname)`, який повертає числовий exit-code, і негайно завершує процес із цим кодом через `process.exit`.
-  - Через `process.exit` подальші асинхронні задачі (мікротаски, відкриті ресурси) можуть бути обірвані — це свідомо: standalone entry-point повинен повертати чіткий код для CI/IDE-інтеграцій.
-- **Локальні правила лінту:**
-  - Поряд із викликом стоїть прагма `// eslint-disable-next-line n/no-process-exit, unicorn/no-process-exit -- standalone entry-point має повертати exit-code для CI/IDE`, оскільки за загальним правилом `process.exit` заборонений, але для CLI-входів дозволений.
-
-## Залежності
-
-### Внутрішні (відносні імпорти)
-
-- `../../scripts/lib/run-rule-cli.mjs`
-  - `isRunAsCli(metaUrl: string): boolean` — детектор «чи запущено модуль як скрипт». Зазвичай порівнює `import.meta.url` із URL виконуваного скрипта (`process.argv[1]`), щоб розрізнити `import` та прямий запуск.
-  - `runRuleCli(ruleDir: string): Promise<number>` — повноцінний CLI-runner: парсить аргументи, читає глобальний config (whitelist, severity, опції), запускає правило з директорії `ruleDir` і друкує summary. Повертає exit-code.
-- `../../scripts/lib/run-standard-rule.mjs`
-  - `runStandardRule(ruleDir: string, ctx?: RuleContext): Promise<number>` — стандартна послідовність кроків для «звичайного» правила: `applies → JS-concerns → policy → mdc-refs`. Це публічне ядро правил-обгорток на кшталт `fix.mjs`.
-  - `RuleContext` (тип) — імпортовано лише в JSDoc для типізації параметра `run`.
-
-### Зовнішні
-
-Прямих залежностей від npm-пакетів файл не має. Усі сторонні бібліотеки, які можуть знадобитися (наприклад, walker, парсер `.mdc`, OPA-обгортки тощо), використовуються транзитивно через `run-standard-rule.mjs` та `run-rule-cli.mjs`.
-
-### Залежність від файлів-побратимів у директорії правила
-
-Хоча `fix.mjs` сам нічого з них не читає, `runStandardRule(import.meta.dirname)` спирається на сусідні артефакти у тій же директорії правила `hasura/`:
-
-- `meta.json` — метадані правила (id, scope, опції тощо);
-- `hasura.mdc` — людинозрозумілий опис правила у форматі Cursor `.mdc`;
-- `js/` — JS-перевірки правила (`check-*.mjs`, fix-helpers);
-- `policy/` — Rego-полісі для OPA-кроку.
-
-Тож структурно файл `fix.mjs` має сенс лише як частина повної папки правила.
-
-## Потік виконання / Використання
-
-### Сценарій A — Library mode (з оркестратора)
+## Огляд
 
-1. Оркестратор (`n-cursor` CLI, агрегатор скілів, тести) робить `import { run } from '<path>/npm/rules/hasura/fix.mjs'`.
-2. Викликає `await run(ctx)`, передаючи контекст із попередньо побудованим `walkCache` та іншими опціями.
-3. `run` синхронно повертає результат виклику `runStandardRule(import.meta.dirname, ctx)`.
-4. `runStandardRule`:
-   - читає `meta.json` із директорії правила;
-   - проганяє послідовність `applies` (фільтр цільових файлів) → JS-concerns (динамічно підвантажені `js/check-*.mjs`) → policy (OPA з `policy/*.rego`) → mdc-refs (валідація `.mdc`-посилань);
-   - агрегує знахідки й повертає кількість порушень як exit-code (`0`/`1`).
-5. Оркестратор підсумовує exit-коди всіх правил.
+Цей файл ініціює застосування правил. Він запускає процес, що включає перевірку JS-занепокоєнь та політик. При самостійному запуску скрипт завантажує конфігурацію та вайтлістинг, а також надає звіт про виконання.
 
-### Сценарій B — Standalone CLI
+## Поведінка
 
-1. Користувач/CI виконує `bun npm/rules/hasura/fix.mjs [args...]`.
-2. На завантаженні модуля Node/Bun обчислює `isRunAsCli(import.meta.url)` — для прямого запуску результат `true`.
-3. Виконується `await runRuleCli(import.meta.dirname)`:
-   - парсинг CLI-аргументів (`--whitelist`, `--severity`, прапори `-q`/`-v` тощо — деталі в `run-rule-cli.mjs`);
-   - підвантаження конфіг-файлу пакета;
-   - застосування whitelist;
-   - виклик внутрішнього еквівалента `runStandardRule` для цієї ж директорії;
-   - друк summary-таблиці результатів.
-4. `process.exit(<exit-code>)` миттєво завершує процес зі значенням, яке повернув `runRuleCli`.
+1. Викликати функцію `run` для виконання правила. Це ініціює процес застосування правил, включаючи перевірку JS-занепокоєнь, політик та посилань MDC.
+2. Якщо скрипт виконується як окрема утиліта (standalone), викликати механізм оркестрації для виконання правила. Це забезпечує повну функціональність, включаючи завантаження конфігурації, вайтлістинг та підсумок.
 
-### Типові випадки використання
+## Публічний API
 
-- **CI:** `bun npm/rules/hasura/fix.mjs` як standalone-крок у пайплайні; ненульовий exit-code зриває build.
-- **Локально:** `npx @nitra/cursor fix hasura` запускає той самий entry-point через диспетчер CLI пакета (а не напряму).
-- **Інтеграція в IDE:** редактор може імпортувати `run` і викликати його в окремому процесі для отримання структурованого результату по правилу `hasura` (наприклад, через виклик `bun -e "import('...fix.mjs').then(m => m.run())"`).
-- **Агрегатори скілів** (наприклад, `n-fix`): паралельно або послідовно імпортують `run` із усіх правил `npm/rules/*/fix.mjs`, передають спільний `ctx` із `walkCache`, щоб уникнути повторного обходу файлової системи.
+run — виконує послідовність дій: застосовує правила, обробляє JavaScript-занепокоєння, перевіряє політику та посилання MDC.
 
-### Технічні зауваження щодо реалізації
+## Гарантії поведінки
 
-- `import.meta.dirname` (Node ≥ 20.11 / Bun) повертає абсолютний шлях до директорії модуля без потреби в `fileURLToPath(import.meta.url)`. Це поточний рекомендований спосіб локалізації власної директорії в ESM-модулях.
-- Прапор `await` у `process.exit(await runRuleCli(...))` працює завдяки top-level await у ESM — додаткової `main()`-обгортки не потрібно.
-- Свідомо обираний `process.exit` (а не «м'який» вихід через `process.exitCode = ...`) гарантує детермінований код повернення для CI/IDE навіть якщо хтось у фоновому таску щось «недописав».
-- Файл нейтральний щодо помилок: `runStandardRule` та `runRuleCli` самі вирішують, чи виносити exception у консоль і конвертувати її в exit-code; `fix.mjs` не обгортає виклики в `try/catch`.
+- Read-only: файл не виконує операцій запису у файлову систему.
+- Кешує результати в межах одного прогону.
+- Не звертається до мережі.

package/rules/image-avif/docs/fix.md

@@ -1,3 +1,9 @@
+---
+docgen:
+  source: npm/rules/image-avif/fix.mjs
+  crc: 12fc1644
+---
+
 # `fix.mjs` — entry-point правила `image-avif`
 
 ## Огляд

package/rules/image-avif/js/docs/avif_generation.md

@@ -1,3 +1,9 @@
+---
+docgen:
+  source: npm/rules/image-avif/js/avif_generation.mjs
+  crc: 101bb0dd
+---
+
 # avif_generation.mjs
 
 ## Огляд

package/rules/js-bun-db/lib/docs/bun-sql-scan.md

@@ -1,3 +1,9 @@
+---
+docgen:
+  source: npm/rules/js-bun-db/lib/bun-sql-scan.mjs
+  crc: 990f04d7
+---
+
 # bun-sql-scan.mjs
 
 ## Огляд
@@ -270,7 +276,7 @@ Set-константи:
 
    ```js
    import { SQL } from 'bun'
-   
+
    /**
     *
     */
@@ -284,7 +290,7 @@ Set-константи:
 
    ```js
    import { sql } from 'bun'
-   
+
    const text = `select * from ${tableName}`
    sql.unsafe(text) // <-- порушення: немає // allow-unsafe: <reason>
    ```
@@ -314,7 +320,7 @@ Set-константи:
 
    ```js
    import { sql } from 'bun'
-   
+
    await sql.end() // <-- порушення: немає // allow-pg-leftover: <reason>
    ```
 

package/rules/js-bun-redis/lib/docs/redis-imports.md

@@ -1,3 +1,9 @@
+---
+docgen:
+  source: npm/rules/js-bun-redis/lib/redis-imports.mjs
+  crc: 887fc929
+---
+
 # redis-imports.mjs
 
 ## Огляд

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

@@ -1,3 +1,9 @@
+---
+docgen:
+  source: npm/rules/js-lint/js/utils_imports.mjs
+  crc: 7eaeaf96
+---
+
 # utils_imports.mjs — перевірка кордону `utils/`-каталогів
 
 ## Огляд

package/rules/js-lint-ci/docs/fix.md

@@ -1,3 +1,9 @@
+---
+docgen:
+  source: npm/rules/js-lint-ci/fix.mjs
+  crc: 12fc1644
+---
+
 # fix.mjs — точка входу правила `js-lint-ci`
 
 ## Огляд
@@ -82,7 +88,7 @@ if (isRunAsCli(import.meta.url)) {
 - **Дія:** виконує `await runRuleCli(import.meta.dirname)` — повний CLI-сценарій (config-loading, whitelist, summary), а потім завершує процес `process.exit(<exit-code>)` з тим самим кодом, що повернув `runRuleCli` (0 або 1) — це критично для CI/IDE, які орієнтуються на код виходу.
 - **Side effects:** завершення процесу (`process.exit`), вся I/O `runRuleCli`. Виклики `process.exit` тут спеціально дозволені директивою:
   ```js
-   
+
   ```
 
 ## Залежності

package/rules/js-mssql/docs/fix.md

@@ -1,3 +1,9 @@
+---
+docgen:
+  source: npm/rules/js-mssql/fix.mjs
+  crc: 12fc1644
+---
+
 # `npm/rules/js-mssql/fix.mjs`
 
 ## Огляд

package/rules/js-mssql/lib/docs/mssql-pool-scan.md

@@ -1,3 +1,9 @@
+---
+docgen:
+  source: npm/rules/js-mssql/lib/mssql-pool-scan.mjs
+  crc: 7490294a
+---
+
 # mssql-pool-scan.mjs
 
 ## Огляд

package/rules/js-run/docs/fix.md

@@ -1,3 +1,9 @@
+---
+docgen:
+  source: npm/rules/js-run/fix.mjs
+  crc: 12fc1644
+---
+
 # fix.mjs — точка входу правила `js-run`
 
 ## Огляд

package/rules/js-run/lib/docs/bunyan-imports.md

@@ -1,3 +1,9 @@
+---
+docgen:
+  source: npm/rules/js-run/lib/bunyan-imports.mjs
+  crc: 5f403a53
+---
+
 # `bunyan-imports.mjs`
 
 ## Огляд

package/rules/js-run/lib/docs/check-env-scan.md

@@ -1,3 +1,9 @@
+---
+docgen:
+  source: npm/rules/js-run/lib/check-env-scan.mjs
+  crc: 56c971d4
+---
+
 # `check-env-scan.mjs` — AST-сканер правила «process.env / CheckEnv»
 
 ## Огляд

package/rules/js-run/lib/docs/conn-file-rules.md

@@ -1,3 +1,9 @@
+---
+docgen:
+  source: npm/rules/js-run/lib/conn-file-rules.mjs
+  crc: 4bebf12c
+---
+
 # conn-file-rules.mjs
 
 ## Огляд

package/rules/js-run/lib/docs/conn-imports-scan.md

@@ -1,3 +1,9 @@
+---
+docgen:
+  source: npm/rules/js-run/lib/conn-imports-scan.mjs
+  crc: 5234d8ba
+---
+
 # conn-imports-scan.mjs
 
 ## Огляд

package/rules/js-run/lib/docs/promise-settimeout-scan.md

@@ -1,3 +1,9 @@
+---
+docgen:
+  source: npm/rules/js-run/lib/promise-settimeout-scan.mjs
+  crc: a7cea379
+---
+
 # promise-settimeout-scan.mjs
 
 ## Огляд

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

@@ -1,3 +1,9 @@
+---
+docgen:
+  source: npm/rules/js-run/lib/temporal-scan.mjs
+  crc: 5b15b070
+---
+
 # temporal-scan.mjs
 
 ## Огляд