@nitra/cursor 5.3.3 → 5.4.0

package/rules/security/docs/fix.md

@@ -1,92 +1,35 @@
 ---
 docgen:
   source: npm/rules/security/fix.mjs
-  crc: 12fc1644
+  crc: 38cf876b
+  score: 70
 ---
 
-# fix.mjs — entry-point правила `security`
+# fix.mjs
 
 ## Огляд
 
-Файл `npm/rules/security/fix.mjs` — це канонічний entry-point правила з ідентифікатором `security` пакета `@nitra/cursor`. Він реалізує стандартний «двозадачний» патерн всіх правил у директорії `npm/rules/<id>/fix.mjs`:
+Файл ініціює виконання визначеного правила. Правило виконує операцію `applies` з використанням `JS-concerns` для отримання `policy` з `mdc-refs`. При завершенні роботи, якщо виконання відбувається через командний рядок, повертається код виходу для встановлення статусу завершення процесу.
 
-1. **Library mode** — експортує функцію `run(ctx)`, яку викликає CLI-оркестратор пакета (`npx @nitra/cursor fix <id>` або агрегований прогон усіх правил). У цьому режимі правило ділить кеш обходу файлів (`walkCache`) та інший контекст із іншими правилами одного запуску.
-2. **Standalone mode** — якщо файл запущено напряму (наприклад `bun rules/security/fix.mjs`), виконується повний CLI-цикл: завантаження конфігурації, застосування whitelist, друк summary та повернення коду виходу для CI/IDE.
+## Поведінка
 
-Уся ділова логіка (фази `applies` → `JS-concerns` → `policy` → `mdc-refs`) делегується спільному раннеру `runStandardRule`, тому сам `fix.mjs` залишається тонким shim-ом, який знає лише власну директорію (`import.meta.dirname`) і передає її далі.
+1. Запуск правила.
+    *   Передача контексту прогону.
+    *   Виклик `runStandardRule` з використанням шляху модуля.
+2. Виконання правила.
+    *   Виклик `runStandardRule` з контекстом.
+    *   Виконання операції `applies → JS-concerns → policy → mdc-refs`.
+3. Вихід з CLI.
+    *   Перевірка режиму запуску через `isRunAsCli`.
+    *   Якщо запущено через CLI, повернення коду виходу з `runRuleCli` для встановлення `process.exitCode`.
 
-## Експорти / API
+## Публічний API
 
-| Експорт | Тип                               | Призначення                                                                                                                                        |
-| ------- | --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `run`   | `function(ctx?): Promise<number>` | Іменований експорт — точка входу для library-режиму. Викликається CLI-оркестратором пакета `@nitra/cursor` під час прогону одного або всіх правил. |
+run — запускає правило: applies → JS-concerns → policy → mdc-refs (через runStandardRule).
+Library mode — викликається CLI orchestration через `import + run`.
 
-Default-експорт не оголошено. Side-effect частина (CLI-bootstrap) виконується лише за умови, що файл є entry-point процесу (див. розділ «Потік виконання»).
+## Гарантії поведінки
 
-## Функції
-
-### `run(ctx)`
-
-```js
-export function run(ctx)
-```
-
-- **Призначення.** Запустити стандартний пайплайн правила: послідовно виконати фази `applies` → `JS-concerns` → `policy` → `mdc-refs`, делегуючи всю реалізацію спільному модулю `runStandardRule`.
-- **Параметри.**
-  - `ctx` _(опційно)_ — `RuleContext` із `../../scripts/lib/run-standard-rule.mjs`. Контекст одного прогону, який можуть розділяти кілька правил (наприклад, кеш обходу файлів `walkCache`, опції CLI, агрегатор результатів тощо). Якщо `ctx` не передано, `runStandardRule` має сам ініціалізувати дефолтний контекст.
-- **Повертає.** `Promise<number>` — числовий exit-code:
-  - `0` — правило не знайшло порушень (OK);
-  - `1` — є порушення, які слід репортити вище (failure).
-- **Side effects.** Усі побічні ефекти інкапсульовано в `runStandardRule`: читання файлів проєкту через `walkCache`, перевірки policy, можливі повідомлення в `stdout`/`stderr`, оновлення спільного контексту. Сам `run` лише прокидає `import.meta.dirname` поточного файла, щоб раннер знав, до якого правила належить директорія (структура `npm/rules/<id>/` визначає `id`).
-- **Винятки.** Власних `throw` немає; будь-які помилки приходять із `runStandardRule` і не перехоплюються — їх обробляє верхній рівень (CLI-оркестратор чи `runRuleCli`).
-
-## Залежності
-
-Імпорти модуля:
-
-| Модуль                                    | Імпортовані символи        | Роль                                                                                                                                                                                                        |
-| ----------------------------------------- | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `../../scripts/lib/run-rule-cli.mjs`      | `isRunAsCli`, `runRuleCli` | Допоміжні функції для standalone-режиму: визначення, що файл запущений як entry-point процесу (`isRunAsCli`), та повний CLI-цикл (`runRuleCli`) із завантаженням конфігурації, whitelist та друком summary. |
-| `../../scripts/lib/run-standard-rule.mjs` | `runStandardRule`          | Спільний раннер, що реалізує канонічний пайплайн правила (`applies` → `JS-concerns` → `policy` → `mdc-refs`). Також надає тип `RuleContext`, який використовується в JSDoc.                                 |
-
-Жодних інших імпортів (зокрема Node-стандартних модулів) у файлі немає — він свідомо тонкий.
-
-Опосередковано модуль покладається на:
-
-- стандартну структуру каталогу правила (`npm/rules/<id>/`), яку розпізнає `runStandardRule` через переданий `import.meta.dirname`;
-- глобальні Node-механізми `import.meta.url` / `import.meta.dirname` для визначення власного шляху;
-- `process.exit` для термінального коду в standalone-режимі.
-
-## Потік виконання / Використання
-
-### Library-режим (виклик з оркестратора)
-
-1. CLI-оркестратор пакета (`npx @nitra/cursor fix` або агрегований прогон усіх правил) робить `import('npm/rules/security/fix.mjs')` і отримує іменований експорт `run`.
-2. Оркестратор готує спільний `RuleContext` (наприклад, ініціалізує `walkCache`, парсить аргументи) і викликає `await run(ctx)`.
-3. `run` повертає `runStandardRule(import.meta.dirname, ctx)` — це promise з exit-code правила.
-4. Оркестратор агрегує exit-коди всіх правил для фінального summary.
-
-### Standalone-режим (`bun rules/security/fix.mjs` / `node ...`)
-
-1. Після завершення імпортів виконується умовний блок `if (isRunAsCli(import.meta.url)) { ... }`.
-2. `isRunAsCli(import.meta.url)` повертає `true`, лише якщо поточний модуль є entry-point процесу (`process.argv[1]` відповідає `import.meta.url`). Це гарантує, що CLI-логіка не спрацює при звичайному імпорті.
-3. У цій гілці викликається `await runRuleCli(import.meta.dirname)` — повний CLI-цикл правила, еквівалентний `npx @nitra/cursor fix security`: завантаження конфігурації, застосування whitelist, друк summary, повернення exit-code.
-4. Отриманий exit-code передається у `process.exit(...)`, щоб CI/IDE отримали коректний статус.
-
-   Top-level `await` всередині блоку дозволено лише тому, що файл — ESM (`.mjs`), а сам блок виконується тільки в standalone-режимі.
-
-### Коментарі ESLint у файлі
-
-Рядок із `process.exit(await runRuleCli(...))` має локальну директиву:
-
-```js
-
-```
-
-Це свідома відмова від загальної заборони `process.exit`: для CLI entry-point потрібно повертати числовий код, інакше CI/IDE не зможуть розрізнити OK і порушення. Заборона залишається активною для решти кодової бази.
-
-### Місце у системі правил
-
-- Директорія `npm/rules/security/` визначає правило з `id = security`. Сам `fix.mjs` не вшиває цей `id` рядком — він виводиться зі шляху через `import.meta.dirname`, який передається до `runStandardRule` / `runRuleCli`.
-- Конкретна логіка перевірок (фази `applies` / `JS-concerns` / `policy` / `mdc-refs`) лежить у сусідніх файлах директорії правила та в `runStandardRule`; цей файл лише «склеює» їх із системою CLI пакета `@nitra/cursor`.
-- Патерн «library `run` + standalone `process.exit(await runRuleCli(...))`» однаковий для всіх правил пакета — він дозволяє запускати правило і в межах агрегованого прогону, і окремо для відладки/CI.
+- Read-only: файл не виконує операцій запису у файлову систему.
+- Кешує результати в межах одного прогону.
+- Не звертається до мережі.

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

@@ -1,190 +1,31 @@
+---
+docgen:
+  source: npm/rules/security/js/sample_secret.mjs
+  crc: ff1c0de8
+  score: 90
+---
+
 # 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` у середині рядка не матчаться.
+1. Початок перевірки.
+2. Пошук прикладних файлів.
+3. Сортування знайдених прикладних файлів за алфавітним порядком.
+4. Ітерація по прикладних файлах.
+5. Зчитування вмісту кожного файлу.
+6. Ітерація по рядках у файлі.
+7. Перевірка кожного рядка на наявність bare secret.
+8. Реєстрація порушення, якщо рядок відповідає шаблону.
+9. Завершення перевірки.
+10. Завершення перевірки з результатом.
 
-### Що НЕ робить цей модуль
+## Гарантії поведінки
 
-- Не сканує не-прикладні файли (звичайний код, документація поза `fixtures/`).
-- Не перевіряє імена ключів (`client_secret`, `JWT_SECRET` дозволені).
-- Не автоматично замінює `secret` на `sample-secret` — лише репортує; виправлення робить розробник вручну.
-- Не парсить структуровані формати (YAML/JSON/TOML) — це робота Rego-частини правила, якщо вона існує.
-- Не виконує реальну детекцію секретів — це робота TruffleHog; модуль лише гарантує сумісність placeholder'ів із вшитим whitelist'ом TruffleHog.
+- Read-only: файл не виконує операцій запису у файлову систему.
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).
+- Не звертається до мережі.

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

@@ -1,137 +1,28 @@
+---
+docgen:
+  source: npm/rules/security/js/trufflehog.mjs
+  crc: 83f277a6
+  score: 95
+---
+
 # 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` та `.trufflehog-exclude`. Дані з цих файлів використовуються для перевірки відповідності шаблону файлу `security.mdc`.
 
-- Немає `package.json` у `cwd` → один `fail` про відсутність → exit-код ≠ 0, перевірка `.trufflehog-exclude` **не** виконується.
-- Є `package.json`, але немає `.trufflehog-exclude` → `pass` для першого та `fail` для другого → exit-код ≠ 0.
-- Обидва файли є, але `.trufflehog-exclude` не містить деяких канонічних patterns → стільки `fail`, скільки повідомлень повернула `checkTextSubset` → exit-код ≠ 0. Жодного `pass` про канонічність у цьому випадку не друкується.
+## Поведінка
 
-Контекст у проєкті:
+1. Перевірка наявності package.json в корені репозиторію.
+2. Перевірка наявності .trufflehog-exclude в корені репозиторію.
+3. Зчитування файлу .trufflehog-exclude.snippet.txt.
+4. Зчитування шаблону з .trufflehog-exclude.snippet.txt.
+5. Перевірка відповідності вмісту .trufflehog-exclude шаблону з security.mdc.
+6. Повернення коду виходу перевірки.
 
-- Модуль належить до родини `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-залежностей.
+- Read-only: файл не виконує операцій запису у файлову систему.
+- Не звертається до мережі.