@nitra/cursor 3.22.0 → 3.23.1

package/rules/security/js/docs/sample_secret.md

@@ -0,0 +1,190 @@
+# sample_secret.mjs
+
+## Огляд
+
+Модуль `sample_secret.mjs` — це FS-частина правила `security`, концерн `sample_secret`. Він реалізує перевірку, що фейкові credential-значення у **прикладних** файлах репозиторію записані як канонічний placeholder `sample-secret`, а не як bare `secret`.
+
+Мотивація: рядок `sample-secret` містить підрядок `sample`, який є у вшитому списку `DefaultFalsePositives` сканера TruffleHog. Завдяки цьому таке значення гарантовано відсіюється сканером незалежно від його версії. Bare `secret` наразі не фіксується TruffleHog лише через випадкову присутність у словнику `fp_words.txt`, що є крихкою поведінкою, залежною від версії інструмента — покладатися на неї не можна.
+
+«Прикладними» вважаються файли, що відповідають хоча б одному з критеріїв:
+
+- basename має суфікс `.example`, `.sample`, `.template` або `.dist` (наприклад, `.env.dist`, `config.example`);
+- basename має infix `.example.`, `.sample.` або `.template.` (наприклад, `docker-compose.example.yml`, `app.config.sample.json`);
+- файл лежить усередині каталогу `fixtures`, `fixture` або `__fixtures__` (на будь-якому рівні дерева).
+
+Решта файлів не сканується — там слово `secret` майже завжди є частиною реального коду, а не placeholder.
+
+Порушенням є лише `secret` у **позиції значення** — одразу після `=`, `:` чи `=>` (з опційними одинарними або подвійними лапками). Імена ключів (`client_secret`, `JWT_SECRET`) свідомо не чіпаються: матч прив'язаний до значення, а не до ключа.
+
+Архітектурний вибір (regex замість AST) пояснюється тим, що прикладні файли — це різнорідні конфіги (`.env`, YAML, JSON, TOML, plain `.dist`), єдиного AST для них немає, тож скан виконується порядково. Вибір JavaScript замість Rego зумовлений необхідністю обходу дерева (`readdir`) для пошуку прикладних файлів, тоді як conftest/Rego парсить лише структуровані документи.
+
+## Експорти / API
+
+Файл є ES-модулем (`.mjs`) і експортує одну публічну функцію:
+
+| Експорт | Тип                                       | Призначення                                                       |
+| ------- | ----------------------------------------- | ----------------------------------------------------------------- |
+| `check` | `async (cwd?: string) => Promise<number>` | Запускає перевірку та повертає exit-код (0 — OK, 1 — є порушення) |
+
+Внутрішні артефакти модуля (не експортуються):
+
+- `EXAMPLE_SUFFIX_RE` — RegExp для перевірки суфікса basename'а прикладного файлу.
+- `EXAMPLE_INFIX_RE` — RegExp для перевірки infix'а у basename'і.
+- `FIXTURE_DIR_RE` — RegExp для виявлення сегмента шляху з фікстурами.
+- `VALUE_SECRET_RE` — RegExp для виявлення bare-`secret` у позиції значення.
+- `isExampleFile(relPosix)` — допоміжна функція класифікації файлу.
+
+## Функції
+
+### `isExampleFile(relPosix)`
+
+**Сигнатура:** `function isExampleFile(relPosix: string): boolean`
+
+**Параметри:**
+
+- `relPosix` (`string`) — відносний шлях файлу від кореня репозиторію у POSIX-форматі (роздільник `/`, не `\`).
+
+**Повертає:** `boolean` — `true`, якщо файл слід сканувати на наявність bare `secret`.
+
+**Логіка:**
+
+1. Виокремлює basename з `relPosix` шляхом обрізання за останнім `/`.
+2. Перевіряє три умови (логічне АБО):
+   - `EXAMPLE_SUFFIX_RE.test(base)` — basename закінчується на `.example`, `.sample`, `.template` або `.dist`.
+   - `EXAMPLE_INFIX_RE.test(base)` — basename містить `.example.`, `.sample.` або `.template.`.
+   - `FIXTURE_DIR_RE.test(relPosix)` — повний відносний шлях містить сегмент `fixtures`, `fixture` або `__fixtures__`.
+3. Повертає результат диз'юнкції.
+
+**Side effects:** немає (чиста функція, працює лише з аргументом).
+
+### `check(cwd?)`
+
+**Сигнатура:** `async function check(cwd?: string): Promise<number>`
+
+**Параметри:**
+
+- `cwd` (`string`, опційний) — абсолютний шлях до кореня репозиторію. За замовчуванням — `process.cwd()`.
+
+**Повертає:** `Promise<number>` — exit-код перевірки:
+
+- `0` — порушень не знайдено (або прикладних файлів не знайдено взагалі);
+- `1` — знайдено хоча б один bare `secret` у позиції значення.
+
+**Алгоритм:**
+
+1. Створює репортер через `createCheckReporter()` і деструктурує з нього методи `pass` і `fail`.
+2. Ініціалізує масив `examples` для зберігання пар `{ abs, rel }` прикладних файлів.
+3. Викликає `walkDir(cwd, callback)` — рекурсивний обхід дерева від `cwd`. У callback'у:
+   - обчислює відносний шлях `rel` через `relative(cwd, abs)`;
+   - нормалізує роздільники до `/` (заміна `sep` на `/`) — це важливо на Windows;
+   - якщо `isExampleFile(rel)` повертає `true`, додає об'єкт у `examples`.
+4. Сортує `examples` за `rel` у лексикографічному порядку (`localeCompare`) — детермінує вихід.
+5. Якщо `examples.length === 0`, репортує `pass('прикладних файлів не знайдено — placeholder перевіряти нема де')` і повертає exit-код репортера.
+6. Інакше для кожного файлу:
+   - читає вміст через `readFile(abs, 'utf8')`;
+   - при будь-якій помилці читання (`try/catch` без re-throw) файл мовчки пропускається — `continue`;
+   - розбиває вміст на рядки за `\n`;
+   - для кожного рядка обрізає завершальний `\r` (CRLF-нормалізація);
+   - тестує рядок проти `VALUE_SECRET_RE`; якщо матч є:
+     - інкрементує лічильник `violations`;
+     - викликає `fail` з повідомленням формату `${rel}:${i + 1}: \`${line.trim()}\` — заміни placeholder \`secret\` на \`sample-secret\` (security.mdc)` (нумерація рядків — 1-based).
+7. Якщо після обходу `violations === 0`, репортує `pass('прикладні файли (${examples.length}) не містять bare \`secret\`')`.
+8. Повертає `reporter.getExitCode()`.
+
+**Side effects:**
+
+- Читання файлової системи: рекурсивний `walkDir` і `readFile` для кожного прикладного файлу.
+- Виклики `pass`/`fail` репортера, який пише повідомлення у stdout/stderr (поведінка інкапсульована в `createCheckReporter`).
+
+**Обробка помилок:** помилки `readFile` ловляться і ігноруються (continue). Це дозволяє пропускати файли без прав читання чи з тимчасовими IO-проблемами без падіння всієї перевірки.
+
+## Залежності
+
+### Стандартна бібліотека Node.js
+
+| Імпорт     | Шлях               | Призначення                                                        |
+| ---------- | ------------------ | ------------------------------------------------------------------ |
+| `readFile` | `node:fs/promises` | Асинхронне читання файлу як UTF-8 рядка                            |
+| `relative` | `node:path`        | Обчислення відносного шляху від `cwd` до абсолютного шляху         |
+| `sep`      | `node:path`        | Платформозалежний роздільник шляхів (`/` на POSIX, `\` на Windows) |
+
+### Внутрішні модулі проєкту
+
+| Імпорт                | Шлях                                      | Призначення                                                                                             |
+| --------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------- |
+| `createCheckReporter` | `../../../scripts/lib/check-reporter.mjs` | Створює об'єкт-репортер з методами `pass`, `fail`, `getExitCode` для уніфікованого виводу check-функцій |
+| `walkDir`             | `../../../scripts/utils/walkDir.mjs`      | Рекурсивний обхід директорії з застосуванням callback'а до кожного файлу                                |
+
+### Регулярні вирази
+
+Усі RegExp мають флаги `u` (Unicode) і, де потрібно, `i` (case-insensitive):
+
+- `EXAMPLE_SUFFIX_RE = /\.(?:example|sample|template|dist)$/iu` — суфікс basename'а.
+- `EXAMPLE_INFIX_RE = /\.(?:example|sample|template)\./iu` — infix у basename'і (без `dist`, бо `dist` доречно лише як кінцевий суфікс).
+- `FIXTURE_DIR_RE = /(?:^|\/)(?:__fixtures__|fixtures?)(?:\/|$)/u` — сегмент шляху з фікстурами (без флага `i`, бо назви каталогів зазвичай у нижньому регістрі).
+- `VALUE_SECRET_RE = /[:=]>?\s*(['"]?)secret\1[\s,;}\])]*(?:(?:#|\/\/).*)?$/iu`:
+  - `[:=]>?` — `=`, `:` або `=>`;
+  - `\s*` — опційні пробіли;
+  - `(['"]?)secret\1` — слово `secret` з опційними **парними** лапками (`'`, `"` або без);
+  - `[\s,;}\])]*` — опційний хвіст (пробіли, кома, крапка з комою, закриваючі дужки);
+  - `(?:(?:#|\/\/).*)?$` — опційний коментар (`#` для shell/YAML/TOML, `//` для JS/JSON5) до кінця рядка;
+  - `$` гарантує, що `secret` — увесь токен значення (`secret-key`, `secretValue` не матчаться);
+  - `[:=]` як префікс відсікає імена ключів (`client_secret`).
+
+## Потік виконання / Використання
+
+### Типовий сценарій запуску
+
+Модуль є точкою FS-частини правила `security/sample_secret`. Викликається оркестратором правил (зазвичай через CLI або CI), який:
+
+1. Імпортує функцію `check` з `npm/rules/security/js/sample_secret.mjs`.
+2. Викликає `await check(repoRoot)`, де `repoRoot` — абсолютний шлях до кореня монорепо.
+3. Передає отриманий exit-код у власний агрегатор результатів.
+
+Приклад прямого виклику з CLI-обгортки:
+
+```js
+import { check } from './sample_secret.mjs'
+
+const code = await check(process.cwd())
+process.exit(code)
+```
+
+### Послідовність дій усередині `check`
+
+```
+walkDir(cwd) ──► фільтр isExampleFile ──► examples[] (відсортовано)
+       │
+       ▼
+для кожного файлу:
+   readFile ──► split('\n') ──► для кожного рядка:
+      ├─ обрізати \r
+      ├─ VALUE_SECRET_RE.test(line)?
+      │    ├─ ні  → пропустити
+      │    └─ так → fail(rel:line: ...); violations++
+       ▼
+violations === 0 ? pass(...) : (вже були fail)
+       ▼
+return reporter.getExitCode()
+```
+
+### Інтеграція з системою правил
+
+- Файл лежить у `npm/rules/security/js/`, що є FS-частиною модульного правила `security` (концерн `sample_secret`).
+- Поряд може існувати Rego/conftest-частина для структурованих перевірок; цей файл відповідає лише за неструктуроване сканування тексту.
+- Репортер `createCheckReporter` повертає exit-код, який інтегрується з загальним пайплайном лінтерів/перевірок проєкту.
+
+### Поведінкові гарантії
+
+- **Детермінізм:** сортування `examples` за `rel.localeCompare` гарантує однаковий порядок повідомлень `fail` на різних запусках.
+- **Кросплатформність:** нормалізація `sep → '/'` забезпечує єдиний формат шляхів у логах і регекспах незалежно від ОС.
+- **Стійкість:** помилки `readFile` ловляться — недоступний файл не валить перевірку.
+- **Точність:** прив'язки `[:=]` зліва і `$` справа у `VALUE_SECRET_RE` мінімізують false positives — імена ключів, складені значення (`secret-key`) і слово `secret` у середині рядка не матчаться.
+
+### Що НЕ робить цей модуль
+
+- Не сканує не-прикладні файли (звичайний код, документація поза `fixtures/`).
+- Не перевіряє імена ключів (`client_secret`, `JWT_SECRET` дозволені).
+- Не автоматично замінює `secret` на `sample-secret` — лише репортує; виправлення робить розробник вручну.
+- Не парсить структуровані формати (YAML/JSON/TOML) — це робота Rego-частини правила, якщо вона існує.
+- Не виконує реальну детекцію секретів — це робота TruffleHog; модуль лише гарантує сумісність placeholder'ів із вшитим whitelist'ом TruffleHog.

package/rules/security/js/docs/trufflehog.md

@@ -0,0 +1,137 @@
+# trufflehog.mjs
+
+## Огляд
+
+Модуль `trufflehog.mjs` — це FS-частина (файлово-системна перевірка) правила `security` з родини cursor-rules монорепозиторію. Його єдина відповідальність — перевірити, що в корені перевіреного репозиторію присутні два артефакти, без яких правило `security.mdc` вважається порушеним:
+
+1. файл `package.json` у корені — самим фактом існування (структуру цього файлу валідує окрема policy `security.package_json` через Rego/OPA, тут вона навмисно не дублюється);
+2. файл `.trufflehog-exclude` у корені, який містить канонічний набір patterns. Оскільки `.trufflehog-exclude` — це plain-text формат (а не JSON/YAML), порівняння виконується методом «text-subset»: усі канонічні рядки зі snippet-шаблону мають бути присутні в репозитарному файлі, але репозиторій може мати додаткові локальні рядки.
+
+Модуль експортує єдину async-функцію `check`, яка повертає exit-код для подальшого використання CLI-обгорткою (наприклад, скриптом-агрегатором перевірок або CI-сценарієм). Усі повідомлення про результат проходять через спільний reporter, тож формат виводу й коди виходу узгоджені з іншими `check-*` модулями цього репозиторію.
+
+Файл вмонтований у конвенцію `npm/rules/<rule>/js/`: він навмисно не виконує мережевих або системних операцій, не пише в файли, не запускає підпроцеси — це чиста read-only перевірка артефактів у переданому або поточному cwd.
+
+## Експорти / API
+
+Модуль експортує лише one named export:
+
+| Експорт | Тип                                                | Призначення                                                                                                      |
+| ------- | -------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| `check` | `async function (cwd?: string) => Promise<number>` | Запустити перевірки FS-частини правила `security` для заданого кореня репозиторію і повернути числовий exit-код. |
+
+Default export відсутній. Жодних інших символів (констант, класів, утиліт) модуль назовні не передає; внутрішні константи `HERE` та `SNIPPET_PATH` залишаються приватними для модуля.
+
+## Функції
+
+### `check(cwd?)`
+
+Головна (і єдина) експортована функція модуля.
+
+Сигнатура:
+
+```
+async function check(cwd: string = process.cwd()): Promise<number>
+```
+
+Параметри:
+
+| Ім'я  | Тип      | Default         | Опис                                                                                                                                                                                                                                                                |
+| ----- | -------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `cwd` | `string` | `process.cwd()` | Абсолютний (або відносний до процесу) шлях до кореня репозиторію, який треба перевірити. Усі шляхи до `package.json` і `.trufflehog-exclude` будують через `join(cwd, ...)`. Якщо параметр не передано — використовується поточний робочий каталог процесу Node.js. |
+
+Повертає: `Promise<number>` — exit-код, який повертає reporter (`reporter.getExitCode()`). Конвенція reporter-а: `0` — усі перевірки `pass`, ненульове значення — є хоча б одна `fail`. Конкретне ненульове значення (1, 2 тощо) визначається реалізацією `createCheckReporter` у `scripts/lib/check-reporter.mjs` і модулем `trufflehog.mjs` не нав'язується.
+
+Покрокова поведінка:
+
+1. Створює локальний reporter через `createCheckReporter()` і деструктурує з нього методи `pass` та `fail` для читабельності викликів.
+2. Перевіряє наявність `package.json` у корені:
+   - якщо файлу немає — викликає `fail('package.json не знайдено в корені — додай (security.mdc)')` і **одразу** повертає `reporter.getExitCode()`, не виконуючи решту перевірок (це early-exit, оскільки без `package.json` решта канонів безпеки втрачає сенс);
+   - якщо файл є — викликає `pass('package.json є (структуру перевіряє Rego)')` і йде далі.
+3. Перевіряє наявність `.trufflehog-exclude` у корені:
+   - якщо файлу немає — викликає `fail('.trufflehog-exclude не знайдено в корені — додай за каноном (security.mdc)')` і повертає exit-код (теж early-exit);
+   - якщо файл є — переходить до text-subset порівняння.
+4. Читає вміст обох файлів — фактичного `.trufflehog-exclude` із cwd та snippet-шаблону `templates/trufflehog/.trufflehog-exclude.snippet.txt` поряд із модулем — в `utf8`.
+5. Викликає `checkTextSubset(actual, template, { targetPath: '.trufflehog-exclude', source: 'security.mdc' })`. Утиліта повертає масив рядків-повідомлень про помилки: порожній масив означає, що всі канонічні patterns з snippet-у наявні у фактичному файлі.
+6. Для кожного повідомлення з `errors` викликає `fail(msg)`. Якщо `errors` порожній — викликає `pass('.trufflehog-exclude містить канонічні patterns')`.
+7. Повертає `reporter.getExitCode()`.
+
+Side effects:
+
+- Читання файлової системи: синхронний `existsSync` (двічі) та асинхронний `readFile` (двічі);
+- Запис у reporter (внутрішній акумулятор стану `pass`/`fail`), який, залежно від реалізації, може писати в `stdout`/`stderr`;
+- Жодних мутацій FS, жодних мережевих викликів, жодних env-залежностей крім стандартного `process.cwd()` як default-значення параметра.
+
+Поведінкові інваріанти:
+
+- Функція **не** кидає винятки в нормальному сценарії «файла нема» — це штатний `fail`. Винятки можливі лише з нижчих рівнів: наприклад, якщо `readFile` не може прочитати існуючий файл через права доступу, або якщо `SNIPPET_PATH` не існує в дистрибутиві модуля (це вже баг дистрибутива, а не вхідних даних).
+- Порядок перевірок фіксований: `package.json` → `.trufflehog-exclude` (наявність) → `.trufflehog-exclude` (text-subset). При фейлі на ранньому кроці наступні **не** виконуються.
+- Перевірка text-subset не вимагає точної рівності файлів: snippet — це мінімум, репозиторій може містити додаткові рядки понад нього.
+
+## Залежності
+
+Built-in модулі Node.js:
+
+- `node:fs` — використовується іменований імпорт `existsSync` для перевірки наявності `package.json` та `.trufflehog-exclude` без читання їхнього вмісту;
+- `node:fs/promises` — іменований імпорт `readFile` для асинхронного читання текстового вмісту обох файлів у кодуванні `utf8`;
+- `node:path` — `dirname` для отримання директорії поточного модуля з його URL і `join` для побудови шляхів до `package.json`, `.trufflehog-exclude` та snippet-шаблону;
+- `node:url` — `fileURLToPath` для перетворення `import.meta.url` у звичайний шлях файлової системи (стандартний ESM-патерн).
+
+Внутрішні модулі репозиторію:
+
+- `../../../scripts/lib/check-reporter.mjs` — фабрика reporter-а `createCheckReporter`. Reporter інкапсулює стан перевірок: акумулює `pass`/`fail`-повідомлення та віддає кінцевий exit-код через `getExitCode()`. Уся семантика виводу (де і як друкується, як кодуються рівні) лежить там.
+- `../../../scripts/lib/template.mjs` — утиліта `checkTextSubset(actual, template, opts)`. Перевіряє, що `template` є підмножиною `actual` (у текстовому сенсі — рядки/блоки шаблону мають зустрічатися у фактичному файлі). Опції `targetPath` та `source` використовуються для форматування повідомлень про помилки (щоб користувач бачив, який саме файл і яке правило порушено).
+
+Файлові артефакти, які модуль читає в runtime:
+
+- `<cwd>/package.json` — фактичний package.json репозиторію, що перевіряється (лише наявність);
+- `<cwd>/.trufflehog-exclude` — фактичний exclude-файл (наявність + вміст);
+- `<HERE>/templates/trufflehog/.trufflehog-exclude.snippet.txt` — канонічний snippet-шаблон, що поставляється разом із модулем. `HERE` = `dirname(fileURLToPath(import.meta.url))`, тобто директорія самого `trufflehog.mjs`. Цей файл — джерело істини для text-subset порівняння.
+
+Зовнішніх npm-залежностей модуль не має.
+
+## Потік виконання / Використання
+
+Типовий сценарій використання — виклик з вищерівневого скрипта-агрегатора перевірок правила `security`, який послідовно прогоняє FS-частину (`trufflehog.mjs`) і policy-частину (Rego/OPA для структури `package.json`). У цій ролі модуль працює як CLI-сумісна функція:
+
+```
+import { check } from './trufflehog.mjs'
+
+const code = await check()           // використає process.cwd()
+process.exit(code)
+```
+
+Або з явним коренем:
+
+```
+import { check } from './trufflehog.mjs'
+
+const code = await check('/path/to/repo')
+process.exit(code)
+```
+
+Послідовність кроків у runtime (happy path):
+
+1. Викликач передає `cwd` (або не передає — береться `process.cwd()`).
+2. Створюється reporter — порожній акумулятор стану.
+3. `existsSync(join(cwd, 'package.json'))` → `true` → `pass(...)`.
+4. `existsSync(join(cwd, '.trufflehog-exclude'))` → `true` → перехід до читання.
+5. Паралельно (через `await` послідовно, але без перехресної залежності) читаються `actual` та `template`.
+6. `checkTextSubset(actual, template, opts)` → `[]` (порожній масив помилок).
+7. Цикл `for (const msg of errors)` нічого не виконує.
+8. Викликається `pass('.trufflehog-exclude містить канонічні patterns')`.
+9. Повертається `reporter.getExitCode()` — у happy-сценарії це `0`.
+
+Гілки відмови (sad paths):
+
+- Немає `package.json` у `cwd` → один `fail` про відсутність → exit-код ≠ 0, перевірка `.trufflehog-exclude` **не** виконується.
+- Є `package.json`, але немає `.trufflehog-exclude` → `pass` для першого та `fail` для другого → exit-код ≠ 0.
+- Обидва файли є, але `.trufflehog-exclude` не містить деяких канонічних patterns → стільки `fail`, скільки повідомлень повернула `checkTextSubset` → exit-код ≠ 0. Жодного `pass` про канонічність у цьому випадку не друкується.
+
+Контекст у проєкті:
+
+- Модуль належить до родини `npm/rules/<rule>/js/` і реалізує JS-half правила `security`. Поряд із ним очікується тека `templates/trufflehog/` з файлом `.trufflehog-exclude.snippet.txt` — без неї `readFile` для snippet кине помилку.
+- Текстовий формат повідомлень `pass`/`fail` ідентичний іншим перевіркам репозиторію (через спільний `check-reporter`), що дозволяє агрегатору одноманітно показувати результати.
+- Розділення «FS-частина перевіряє наявність, Rego — структуру» — навмисний design choice: він зафіксований у `security.mdc` і повторений у doc-string модуля. У `trufflehog.mjs` **не** можна додавати парсинг JSON `package.json` чи логіку валідації полів — це порушує контракт із Rego-policy.
+- text-subset (а не точна рівність) обраний саме тому, що `.trufflehog-exclude` — plain text без структури: канон постачає мінімум обов'язкових patterns, а команди можуть розширювати свій exclude-файл локальними правилами без порушення security-канону.
+
+Rebuild test: за цією документацією можна відновити поведінку модуля від інтерфейсу до side-effects — сигнатуру `check`, default-значення `cwd`, послідовність двох FS-перевірок з early-exit, виклик `checkTextSubset` з опціями `targetPath`/`source`, формування exit-коду через `reporter.getExitCode()`, перелік повідомлень `fail`/`pass` і відсутність зовнішніх npm-залежностей.

package/rules/security/js/lint.mjs

@@ -11,7 +11,15 @@ import { spawnSync } from 'node:child_process'
 export function lint(_files, cwd = process.cwd()) {
   const r = spawnSync(
     'trufflehog',
-    ['filesystem', '.', '--no-update', '--exclude-paths', '.trufflehog-exclude', '--results=verified,unknown', '--fail'],
+    [
+      'filesystem',
+      '.',
+      '--no-update',
+      '--exclude-paths',
+      '.trufflehog-exclude',
+      '--results=verified,unknown',
+      '--fail'
+    ],
     { cwd, stdio: 'inherit' }
   )
   return Promise.resolve(typeof r.status === 'number' ? r.status : 1)

package/rules/style-lint/docs/fix.md

@@ -0,0 +1,155 @@
+# fix.mjs — точка входу правила `style-lint`
+
+## Огляд
+
+Файл `npm/rules/style-lint/fix.mjs` — це точка входу (entry-point) правила з ідентифікатором `style-lint` у системі `@nitra/cursor`. Він виконує дві ролі одночасно:
+
+1. **Library mode** — експортує функцію `run(ctx)`, яку зовнішній CLI-оркестратор (`npx @nitra/cursor fix <id>` чи внутрішній диспетчер правил) імпортує й запускає в межах загального прогону пакета правил.
+2. **Standalone mode** — якщо файл запущено напряму через `bun rules/style-lint/fix.mjs`, він самостійно ініціалізує конфіг, whitelist, summary та повертає exit-code, повністю еквівалентний виклику `npx @nitra/cursor fix style-lint`.
+
+Сам файл навмисно тонкий: вся логіка перевірок винесена у спільні утиліти `runStandardRule` (стандартний пайплайн правила: `applies → JS-concerns → policy → mdc-refs`) і `runRuleCli` (обгортка для standalone-запуску). Це канонічна форма entry-point для будь-якого правила в монорепо `@nitra/cursor`, що дозволяє додавати нові правила, не дублюючи orchestration-код.
+
+Правило `style-lint` оперує над стилями (Style/CSS-частина) — деталі його перевірок мешкають у сусідніх теках (`js/`, `policy/`, `style-lint.mdc`), але сам цей файл їх не імпортує: пайплайн виявляє їх автоматично за конвенцією директорії `import.meta.dirname`.
+
+## Експорти / API
+
+| Експорт | Тип                                               | Призначення                                                                                                   |
+| ------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| `run`   | `function (ctx?: RuleContext) => Promise<number>` | Запускає стандартний пайплайн правила `style-lint`. Повертає `0` за відсутності порушень, `1` — за наявності. |
+
+Експорт `run` — це **публічний контракт правила**. Будь-який оркестратор, що знає лише шлях до директорії правила, може динамічно імпортувати `fix.mjs` і викликати `run(ctx)`.
+
+Жодних інших іменованих експортів, default-експорту, констант чи класів файл не надає.
+
+## Функції
+
+### `run(ctx)`
+
+```js
+export function run(ctx) {
+  return runStandardRule(import.meta.dirname, ctx)
+}
+```
+
+- **Сигнатура:** `run(ctx?: RuleContext): Promise<number>`
+- **Параметри:**
+  - `ctx` (необов'язковий) — об'єкт контексту прогону типу `RuleContext` (визначений у `../../scripts/lib/run-standard-rule.mjs`). Містить, зокрема, `walkCache` — кеш обходу файлової системи, який оркестратор переюзує між правилами, щоб не сканувати дерево повторно. Якщо `ctx` не передано — `runStandardRule` створить дефолтний контекст самостійно.
+- **Повертає:** `Promise<number>` — exit-code:
+  - `0` — правило виконано, порушень не знайдено;
+  - `1` — знайдено порушення (CI має зафейлити збірку).
+- **Side effects:**
+  - Звертається до файлової системи через `runStandardRule` (читає файли проєкту, що підпадають під `applies`-фільтр правила).
+  - Може писати у stdout/stderr (summary, помилки) через утиліти всередині `runStandardRule`.
+  - Сам по собі функція **не** мутує жодного файлу — навіть для правил із суфіксом `fix.mjs` пайплайн у режимі звичайного прогону є read-only (модифікації виконуються в окремих fix-режимах, які тут не задіяні).
+- **Як працює:** делегує всю роботу `runStandardRule`, передаючи їй власну директорію (`import.meta.dirname` = абсолютний шлях до `npm/rules/style-lint/`). Пайплайн всередині послідовно прогонить чотири фази:
+  1. **applies** — визначення, які файли проєкту підпадають під дію правила;
+  2. **JS-concerns** — JS/MJS-перевірки (логіка з `js/`);
+  3. **policy** — Rego/політики (логіка з `policy/`);
+  4. **mdc-refs** — звірення посилань у `style-lint.mdc` (актуальність документації).
+
+### Standalone-блок (top-level `if`)
+
+```js
+if (isRunAsCli(import.meta.url)) {
+  process.exit(await runRuleCli(import.meta.dirname))
+}
+```
+
+- **Не функція**, а top-level guard, що виконується лише коли файл стартує безпосередньо як CLI-точка (а не імпортується іншим модулем).
+- **Детект:** `isRunAsCli(import.meta.url)` повертає `true`, коли `import.meta.url` відповідає аргументу запуску процесу (тобто `bun npm/rules/style-lint/fix.mjs` чи `node npm/rules/style-lint/fix.mjs`).
+- **Дія:** викликає `runRuleCli(import.meta.dirname)`, яка проганяє повний цикл CLI (config-loading, whitelist, summary, exit-code) і завершує процес через `process.exit` зі здобутим кодом.
+- **Чому `await` на верхньому рівні:** файл — ES-модуль `.mjs`, top-level `await` дозволений.
+- **Eslint-винятки:** `n/no-process-exit` та `unicorn/no-process-exit` навмисно відключені рядковим коментарем, бо для standalone entry-point явний `process.exit` — єдиний коректний спосіб віддати exit-code CI/IDE.
+
+## Залежності
+
+### Внутрішні (relative imports)
+
+| Модуль                                    | Що з нього імпортовано     | Роль                                                                                                                           |
+| ----------------------------------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| `../../scripts/lib/run-rule-cli.mjs`      | `isRunAsCli`, `runRuleCli` | Утиліти standalone-режиму: детект CLI-запуску та повний CLI-цикл (config + whitelist + summary).                               |
+| `../../scripts/lib/run-standard-rule.mjs` | `runStandardRule`          | Стандартний пайплайн правила (applies → JS-concerns → policy → mdc-refs). Також надає тип `RuleContext` (через JSDoc-typedef). |
+
+Шляхи `../../scripts/lib/...` обчислюються відносно `npm/rules/style-lint/` і вказують на `npm/scripts/lib/`.
+
+### Зовнішні
+
+- **Жодних** npm-пакетів файл напряму не імпортує. Усі залежності — внутрішні.
+- **Runtime:** Node.js / Bun з підтримкою ESM, `import.meta.url`, `import.meta.dirname` та top-level `await`.
+
+### Сусідні артефакти правила (не імпортуються тут, але задіяні через пайплайн)
+
+- `npm/rules/style-lint/meta.json` — метадані правила (id, applies-патерни тощо), читається `runStandardRule`/`runRuleCli`.
+- `npm/rules/style-lint/style-lint.mdc` — людиночитна специфікація правила (target для mdc-refs-фази).
+- `npm/rules/style-lint/js/` — JS-частина перевірок (підвантажується JS-concerns-фазою).
+- `npm/rules/style-lint/policy/` — Rego-політики (підвантажуються policy-фазою).
+
+## Потік виконання / Використання
+
+### Сценарій A — імпорт оркестратором (library mode)
+
+```text
+@nitra/cursor CLI (або інший runner)
+        │
+        │ dynamic import('npm/rules/style-lint/fix.mjs')
+        ▼
+fix.mjs → export run(ctx)
+        │
+        │ runStandardRule(import.meta.dirname, ctx)
+        ▼
+run-standard-rule.mjs
+        │
+        ├── applies-фаза (фільтр файлів)
+        ├── JS-concerns-фаза (js/)
+        ├── policy-фаза (policy/)
+        └── mdc-refs-фаза (style-lint.mdc)
+        │
+        ▼
+        return 0 | 1
+```
+
+Оркестратор зазвичай передає `ctx` із попередньо побудованим `walkCache`, щоб уникнути повторного обходу файлового дерева між десятками правил.
+
+### Сценарій B — пряма CLI-точка (standalone mode)
+
+```text
+$ bun npm/rules/style-lint/fix.mjs
+        │
+        │ Node/Bun завантажує fix.mjs як головний модуль
+        ▼
+import-блок виконано → run експортовано
+        │
+        ▼
+top-level if (isRunAsCli(import.meta.url))   // true
+        │
+        │ await runRuleCli(import.meta.dirname)
+        ▼
+run-rule-cli.mjs
+        │
+        ├── завантажує конфіг проєкту
+        ├── застосовує whitelist
+        ├── викликає внутрішньо аналог run(ctx)
+        ├── друкує summary
+        └── повертає number (exit-code)
+        │
+        ▼
+process.exit(<exit-code>)
+```
+
+Цей режим використовується розробником локально (`bun npm/rules/style-lint/fix.mjs`) або IDE-інтеграцією, що очікує POSIX exit-code.
+
+### Інваріанти та контракт
+
+- Файл — **stateless**: жодних модульних змінних, кешів, синглтонів. Усе передається через `ctx`.
+- Функція `run` **ідемпотентна** щодо файлової системи (read-only прогон).
+- `run` **завжди** повертає `Promise<number>` зі значенням `0` або `1` — оркестратор не повинен очікувати інших значень чи кидків.
+- Standalone-блок виконується **виключно** коли файл — головний модуль; при `import` із іншого коду блок мовчазно пропускається завдяки `isRunAsCli`.
+
+### Як додати аналогічний entry-point для нового правила
+
+1. Створити теку `npm/rules/<new-rule-id>/`.
+2. Скопіювати цей `fix.mjs` без змін (шляхи відносні до `npm/rules/<id>/` ідентичні).
+3. Покласти поруч `meta.json`, `<new-rule-id>.mdc`, `js/`, `policy/` за потреби.
+4. Пайплайн `runStandardRule` підхопить нове правило автоматично, без правок самого `fix.mjs`.
+
+Це і є цінність «тонкого» entry-point: правила додаються декларативно, без дублювання orchestration-логіки.