@nitra/cursor 3.22.0 → 3.23.1

package/rules/rust/js/docs/applies.md

@@ -0,0 +1,140 @@
+# applies.mjs
+
+## Огляд
+
+Модуль `applies.mjs` реалізує **applies-гейт** для правила `rust` у системі правил `n-cursor`. Його завдання — швидко відповісти на питання: «чи має взагалі сенс прогонити це правило в поточному репозиторії?». Якщо репозиторій не містить жодного Rust-кореня (тобто немає `Cargo.toml` ані в корені, ані в жодному вкладеному робочому каталозі), функція повертає `false`, і ранер `runStandardRule` пропускає всі концерни цього правила — як JS-перевірки, так і policy-концерни. Це уникає зайвої роботи в репозиторіях без Rust-коду.
+
+Маркером застосовності є файл `Cargo.toml`:
+
+- спершу швидка перевірка в `cwd` через `existsSync` (синхронно, без I/O-обходу);
+- якщо в корені маркера немає — рекурсивний обхід дерева через `hasCargoTomlInTree`, який ігнорує штучні / службові директорії (`node_modules`, `.git`, `.next`, `.turbo`).
+
+Окремо експортується функція `check()` — це **context-pass** репортер: коли applies повернув `true`, ранер усе одно очікує, що файл правила розрукує хоча б один контекст. `check()` просто друкує повідомлення «знайдено Cargo.toml — застосовуємо правила rust.mdc» і повертає exit-код `0`. Жодної реальної логіки лінтування / перевірок у цьому файлі немає — вся робота винесена в **policy-концерни** правила `rust`.
+
+Файл написаний у форматі ESM (`.mjs`) та сумісний з Bun і Node.js (≥ модулів з підтримкою ESM та `node:` префіксу).
+
+## Експорти / API
+
+| Експорт   | Тип                                  | Призначення                                                              |
+| --------- | ------------------------------------ | ------------------------------------------------------------------------ |
+| `applies` | `(cwd?: string) => Promise<boolean>` | Гейт-функція: чи активувати правило `rust` для заданого `cwd`.           |
+| `check`   | `() => number`                       | Context-pass репортер: друкує позитивне повідомлення, повертає exit-код. |
+
+Інших публічних експортів немає. Константа `IGNORED_DIR_NAMES` — внутрішня (module-level), назовні не експортується.
+
+## Функції
+
+### `applies(cwd = process.cwd())`
+
+**Сигнатура:** `applies(cwd?: string): Promise<boolean>`
+
+**Параметри:**
+
+- `cwd` _(string, опційний)_ — абсолютний (або відносний від процесу) шлях до кореня репозиторію, який треба перевірити. За замовчуванням — `process.cwd()` (поточний робочий каталог процесу Node/Bun).
+
+**Повертає:** `Promise<boolean>`
+
+- `true` — правило `rust` застосовне (знайдено хоча б один `Cargo.toml` у корені або десь у дереві);
+- `false` — застосовувати правило не треба (Rust у репозиторії не знайдено).
+
+**Алгоритм:**
+
+1. Складає шлях `join(cwd, 'Cargo.toml')` і синхронно перевіряє його існування через `existsSync`.
+2. Якщо файл є — одразу повертає `Promise.resolve(true)` (швидкий вихід; решта дерева не сканується).
+3. Якщо в корені маркера немає — викликає `hasCargoTomlInTree(cwd, IGNORED_DIR_NAMES)` і повертає його результат, загорнутий у промісі (значення може бути проміс або bool — у будь-якому разі `Promise.resolve` нормалізує до `Promise<boolean>`).
+
+**Side effects:**
+
+- Один синхронний виклик `existsSync` (file-system stat) для шляху `<cwd>/Cargo.toml`.
+- За потреби — рекурсивний обхід директорії `cwd` (виконує `hasCargoTomlInTree`); у межах цього обходу директорії з `IGNORED_DIR_NAMES` пропускаються.
+- Не модифікує файлову систему, не пише в `stdout`/`stderr`, не виконує мережевих запитів.
+
+**Не кидає винятків** у нормальних умовах: `existsSync` повертає `false` для неіснуючих/недоступних шляхів. Виняткові ситуації можуть прилетіти лише з глибин `hasCargoTomlInTree` (наприклад, помилка `readdir`), але це поведінка залежного модуля, а не самого `applies`.
+
+### `check()`
+
+**Сигнатура:** `check(): number`
+
+**Параметри:** немає.
+
+**Повертає:** `number` — exit-код:
+
+- `0` — все OK (стандартний шлях; функція завжди йде цим шляхом, бо вона лише друкує `pass`);
+- `1` — порушення (теоретично можливо, якщо репортер у майбутньому почне накопичувати помилки; зараз цей кейс не використовується).
+
+**Алгоритм:**
+
+1. Створює інстанс репортера через `createCheckReporter()`.
+2. Викликає `reporter.pass('Знайдено Cargo.toml — застосовуємо правила rust.mdc')` — реєструє позитивний context-pass.
+3. Повертає `reporter.getExitCode()`.
+
+**Side effects:**
+
+- Друкує повідомлення про `pass` у stdout у форматі, заданому `createCheckReporter` (зазвичай — рядок з префіксом / маркером).
+- Не торкається файлової системи й мережі.
+
+**Контракт із ранером:** `runStandardRule` викликає `check()` лише після того, як `applies()` повернув `true`. Тому повідомлення в стилі «знайдено Cargo.toml» завжди коректне на момент друку — applies-гейт уже відпрацював перед цим.
+
+## Залежності
+
+### Зовнішні (стандартна бібліотека Node.js)
+
+- `node:fs` → `existsSync` — синхронна перевірка існування файлу.
+- `node:path` → `join` — крос-платформне склеювання сегментів шляху.
+
+### Внутрішні (відносні до файлу)
+
+- `../../../scripts/lib/check-reporter.mjs` → `createCheckReporter` — фабрика репортера для context-pass / помилок із підрахунком exit-коду.
+- `../lib/has-cargo-toml.mjs` → `hasCargoTomlInTree` — рекурсивний обхід дерева директорій з пошуком `Cargo.toml` і пропуском ігнор-папок.
+
+### Module-level константи
+
+- `IGNORED_DIR_NAMES: Set<string>` — `{ 'node_modules', '.git', '.next', '.turbo' }`. Передається в `hasCargoTomlInTree` як набір імен директорій, у які заходити не треба під час рекурсивного пошуку.
+
+## Потік виконання / Використання
+
+### Типовий сценарій (ранер правил)
+
+1. `runStandardRule` для правила `rust` спершу імпортує модуль `applies.mjs`.
+2. Викликає `await applies()` (без аргументів — буде використано `process.cwd()`).
+3. Якщо результат `false` — ранер пропускає правило цілком: ні JS-концерни (`check`), ні policy-концерни не виконуються; правило вважається «not applicable».
+4. Якщо результат `true` — ранер послідовно виконує всі концерни правила:
+   - викликає експортований `check()` як «context-pass» — щоб у звіті був видимий маркер «правило застосовано»;
+   - запускає policy-концерни (фактичні перевірки коду / структури), які живуть в інших файлах модуля `rust`.
+
+### Приклад прямого виклику
+
+```js
+import { applies, check } from './npm/rules/rust/js/applies.mjs'
+
+const ok = await applies('/path/to/some/repo')
+if (ok) {
+  const code = check()
+  process.exit(code)
+}
+```
+
+### Ребра (edge cases)
+
+- **`cwd` не існує / недоступний:** `existsSync` поверне `false`; далі `hasCargoTomlInTree` обходитиме неіснуючий шлях (поведінка визначається ним).
+- **`Cargo.toml` лежить глибоко під ігнор-папкою** (наприклад, всередині `node_modules/.../Cargo.toml`): його **не** знайдуть — `IGNORED_DIR_NAMES` свідомо пропускає такі директорії, бо це не «справжній» Rust-корінь репозиторію.
+- **`Cargo.toml` у корені `cwd`:** виконується лише `existsSync` — рекурсивний обхід не запускається (оптимізація).
+- **Множинні `Cargo.toml` глибоко в дереві:** достатньо знайти хоча б один — `hasCargoTomlInTree` має повернути `true` при першому ж збігу.
+
+### Інваріанти
+
+- `applies()` завжди повертає `Promise<boolean>` — навіть для синхронного fast-path через `Promise.resolve(true)`.
+- `check()` синхронна — не повертає Promise; завжди повертає число (exit-код).
+- `applies()` ідемпотентна та не має станy між викликами (немає кешу).
+
+## Rebuild Test
+
+Якщо видалити файл `applies.mjs` і відновлювати його з нуля по цій документації, реалізація має:
+
+- бути ESM-модулем (`.mjs`) з ES-імпортами `node:fs` / `node:path`;
+- імпортувати `createCheckReporter` із `../../../scripts/lib/check-reporter.mjs` і `hasCargoTomlInTree` із `../lib/has-cargo-toml.mjs`;
+- містити module-level `Set` з рівно цими іменами: `'node_modules'`, `'.git'`, `'.next'`, `'.turbo'`;
+- експортувати **named** функцію `applies(cwd = process.cwd())` з логікою «`existsSync(join(cwd, 'Cargo.toml'))` → інакше делегат у `hasCargoTomlInTree(cwd, IGNORED_DIR_NAMES)`», результати загорнуті в `Promise.resolve`;
+- експортувати **named** синхронну функцію `check()`, яка створює репортер, реєструє `pass('Знайдено Cargo.toml — застосовуємо правила rust.mdc')` і повертає `reporter.getExitCode()`;
+- не мати default-експорту;
+- не мати побічних ефектів на рівні модуля (тільки декларація `Set` — допустимо).

package/rules/rust/lib/docs/has-cargo-toml.md

@@ -0,0 +1,130 @@
+# has-cargo-toml.mjs
+
+## Огляд
+
+Модуль `has-cargo-toml.mjs` — rule-local утиліта для правил Rust, що визначає наявність маніфесту Cargo (`Cargo.toml`) у дереві файлової системи, починаючи з заданого кореневого каталогу. Використовується як applies-walker на рівні правила: дозволяє правилу Rust динамічно вирішувати, чи варто застосовуватися до конкретного workspace/cwd, шукаючи `Cargo.toml` у поточному каталозі або в будь-якому з підкаталогів.
+
+Реалізація — синхронний рекурсивний обхід каталогів з раннім поверненням (`early return`) при першому ж знайденому `Cargo.toml`, без читання вмісту файлів. Імена директорій, у які заходити не треба (наприклад, `node_modules`, `.git`, `.next`, `.turbo`), передаються ззовні через `Set<string>` — модуль свідомо не містить власного списку, щоб список ігнорувань був єдиним з тим, що в `npm/scripts/auto-rules.mjs` (на рівні виклику).
+
+Утиліта навмисно тримається rule-local (у каталозі правила `rust/lib/`), оскільки на момент написання її єдиний споживач — правило `rust`. У документуючому коментарі модуля зазначено: якщо з'явиться другий споживач — утиліту слід підняти у спільний `npm/scripts/lib/`.
+
+## Експорти / API
+
+Модуль експортує одну іменовану функцію:
+
+- `hasCargoTomlInTree(root, ignoredDirNames)` — `function`, named export.
+
+Інших експортів (default, типів, констант) у модулі немає.
+
+## Функції
+
+### `hasCargoTomlInTree(root, ignoredDirNames)`
+
+**Сигнатура:**
+
+```js
+export function hasCargoTomlInTree(root: string, ignoredDirNames: Set<string>): boolean
+```
+
+**Параметри:**
+
+- `root` — `string`. Абсолютний шлях до кореневого каталогу, з якого починається пошук. Передається у внутрішню функцію `walk` як стартова точка обходу.
+- `ignoredDirNames` — `Set<string>`. Множина імен директорій (саме базових імен — не шляхів), у які НЕ слід заходити під час обходу. Перевірка виконується через `ignoredDirNames.has(entry.name)`. Типові значення, які формує викликова сторона: `'node_modules'`, `'.git'`, `'.next'`, `'.turbo'`.
+
+**Повертає:**
+
+- `boolean` — `true`, якщо в піддереві з коренем `root` (включно з самим `root`) знайдено хоча б один файл з ім'ям `Cargo.toml`. `false` — якщо такого файла немає, або якщо корінь недоступний для читання.
+
+**Алгоритм:**
+
+1. Викликається внутрішня функція `walk(root)`.
+2. Усередині `walk(dir)` робиться спроба отримати вміст каталогу через `readdirSync(dir, { withFileTypes: true })`, що повертає масив об'єктів `Dirent`.
+3. Якщо `readdirSync` кидає виключення (наприклад, `EACCES`, `ENOENT`, `ENOTDIR`) — воно мовчки ловиться `catch {}` і функція повертає `false` для цього каталогу (обхід продовжується для інших гілок, якщо вони є).
+4. Виконується ітерація по `entries`:
+   - Якщо запис — це файл і його ім'я дорівнює рівно `'Cargo.toml'`, негайно повертається `true` (early return).
+   - Якщо запис — це каталог і його ім'я не входить у `ignoredDirNames`, рекурсивно викликається `walk(join(dir, entry.name))`; при `true` від рекурсії — негайно повертається `true`.
+5. Якщо жоден запис не дав `true`, повертається `false`.
+
+Порядок обходу — детерміністичний у межах одного запуску і визначається порядком, який повертає `readdirSync` (як правило, залежить від ФС/ОС). Це означає, що логічний результат (boolean) детерміністичний, але швидкість виявлення `Cargo.toml` залежить від порядку записів.
+
+Алгоритм має властивість «depth-first з раннім return»: знайшовши `Cargo.toml` у першій же підгілці, функція не обходить решту дерева.
+
+**Side effects:**
+
+- Виключно синхронні I/O-операції читання вмісту директорій через `readdirSync` із Node.js `fs`. Не читає вміст файлів, не пише на диск, не звертається до мережі, не змінює глобальний стан.
+- При помилках доступу до окремого каталогу не пробрасує виключення назовні — глушить їх через `try/catch` і повертає `false` лише для проблемної гілки.
+- Блокує event loop на час обходу (синхронне API). Для дуже великих дерев це може бути помітним; ризик частково мітигує ранній return і список `ignoredDirNames`, що відсікає типові важкі директорії на кшталт `node_modules`.
+
+**Внутрішня функція `walk(dir)`:**
+
+- `dir` — `string`, абсолютний шлях каталогу для обходу.
+- Повертає `boolean` — `true`, якщо в піддереві `dir` є `Cargo.toml`.
+- Замикається на параметр `ignoredDirNames` зовнішньої функції (тобто множина передається один раз і використовується на всіх рівнях рекурсії без повторної параметризації).
+
+## Залежності
+
+Зовнішні npm-залежності — відсутні. Модуль працює виключно на стандартній бібліотеці Node.js:
+
+- `node:fs` — імпортується `readdirSync` для синхронного читання вмісту каталогу з опцією `withFileTypes: true`, що повертає `Dirent[]` (для уникнення додаткових `statSync` на кожен запис).
+- `node:path` — імпортується `join` для безпечного склеювання шляхів `dir + entry.name` із врахуванням розділювача ОС.
+
+Імпорти використовують префікс `node:` (`node:fs`, `node:path`) — це канонічна форма посилання на вбудовані модулі Node.js, що відрізняє їх від npm-пакунків.
+
+Модуль написаний як ES Module (`.mjs`): використовуються `import` та `export`.
+
+Внутрішніх залежностей від інших файлів проєкту немає — модуль повністю самодостатній.
+
+## Потік виконання / Використання
+
+### Контекст застосування
+
+Функція проектована як applies-walker для правил Rust: правило викликає її, щоб дізнатися, чи має воно сенс у поточному репозиторії/workspace. Якщо `Cargo.toml` ніде не знайдено — правило застосовувати не треба.
+
+### Типовий виклик
+
+```js
+import { hasCargoTomlInTree } from './lib/has-cargo-toml.mjs'
+
+const IGNORED = new Set(['node_modules', '.git', '.next', '.turbo'])
+
+if (hasCargoTomlInTree(process.cwd(), IGNORED)) {
+  // правило Rust застосовується: десь у дереві є Cargo.toml
+} else {
+  // Rust-проєкту не виявлено — правило пропускається
+}
+```
+
+Список ігнорованих директорій формується викликовою стороною й має співпадати зі списком, який використовує `npm/scripts/auto-rules.mjs` (це вимога з заголовного коментаря модуля — щоб поведінка обходу була узгоджена між скриптом авто-правил і rule-local утилітою).
+
+### Розгортання потоку виконання
+
+1. Споживач (правило Rust) формує `Set<string>` ігнорованих імен директорій.
+2. Споживач викликає `hasCargoTomlInTree(root, ignoredDirNames)` із кореневим шляхом (зазвичай — поточний workspace або репозиторій).
+3. Усередині функції стартує `walk(root)`:
+   - Якщо `root` сам містить `Cargo.toml` як файл першого рівня — повертається `true` без рекурсії далі по цьому ж рівню (інші записи не перевіряються після першого ж `Cargo.toml`).
+   - Якщо `Cargo.toml` на першому рівні немає — обхід заглиблюється у кожен підкаталог, якого немає в `ignoredDirNames`.
+   - Перший же `true` із рекурсії припиняє обхід і пробрасує `true` нагору.
+4. Якщо все дерево пройдене без знахідки — повертається `false`.
+5. Споживач використовує boolean-результат для прийняття рішення про застосування правила.
+
+### Граничні випадки
+
+- **Порожній `ignoredDirNames`** (`new Set()`): функція обходить геть усе дерево, включно з `node_modules` тощо — це коректно, але повільно.
+- **Неіснуючий `root`**: `readdirSync` кидає `ENOENT`, помилка ловиться, функція повертає `false`.
+- **`root` не є директорією** (наприклад, шлях до файлу): `readdirSync` кидає `ENOTDIR`, ловиться `catch`, повертається `false`.
+- **Cargo.toml як директорія**: пропускається, бо перевірка йде через `entry.isFile() && entry.name === 'Cargo.toml'` — потрібен саме файл.
+- **Симлінки**: `withFileTypes: true` повертає `Dirent` з власними методами; `entry.isFile()` для симлінка поверне `false`, `entry.isDirectory()` — теж `false` (метод `isSymbolicLink()` тут не перевіряється), тож симлінки фактично не переходяться. Це свідомий вибір — захист від циклів через симлінки.
+- **Cargo.toml у самому корені**: знаходиться на першому ж рівні без рекурсії.
+- **Cargo.toml виключно всередині `node_modules`** (за умови, що `node_modules` у `ignoredDirNames`): не знаходиться, функція повертає `false`. Це навмисна поведінка: ні правила, ні авто-обхід не повинні «бачити» вендоровані Rust-маніфести з npm-залежностей.
+
+### Контекст у проєкті
+
+Згідно з заголовним коментарем файлу:
+
+- Утиліта живе у `npm/rules/rust/lib/` як rule-local — лише `rust`-правило її використовує.
+- Список ігнорованих директорій має узгоджуватися зі списком у `npm/scripts/auto-rules.mjs`.
+- Інваріант масштабування: при появі другого споживача — підняти модуль у спільний `npm/scripts/lib/`.
+
+## Rebuild Test
+
+За цією документацією модуль можна відтворити: один ES-модуль з імпортами `readdirSync` із `node:fs` та `join` із `node:path`, що експортує іменовану функцію `hasCargoTomlInTree(root, ignoredDirNames)`. Усередині — внутрішня рекурсивна функція `walk(dir)` із синхронним `readdirSync(dir, { withFileTypes: true })`, обгорнутим у `try/catch`, ітерацією по `Dirent`-записах, перевіркою `isFile() && name === 'Cargo.toml'` для негайного `true`, та рекурсією у підкаталоги через `join(dir, entry.name)` за умови `isDirectory() && !ignoredDirNames.has(name)`. Поведінкові інваріанти: ранній return при знахідці; повернення `false` при помилці читання каталогу; пропуск ігнорованих директорій; обхід не йде у симлінки (бо `isDirectory()` для симлінка повертає `false`); жодних побічних ефектів окрім читання структури директорій. Сигнатура: `(string, Set<string>) => boolean`.

package/rules/security/docs/fix.md

@@ -0,0 +1,86 @@
+# fix.mjs — entry-point правила `security`
+
+## Огляд
+
+Файл `npm/rules/security/fix.mjs` — це канонічний entry-point правила з ідентифікатором `security` пакета `@nitra/cursor`. Він реалізує стандартний «двозадачний» патерн всіх правил у директорії `npm/rules/<id>/fix.mjs`:
+
+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`) і передає її далі.
+
+## Експорти / API
+
+| Експорт | Тип                               | Призначення                                                                                                                                        |
+| ------- | --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `run`   | `function(ctx?): Promise<number>` | Іменований експорт — точка входу для library-режиму. Викликається CLI-оркестратором пакета `@nitra/cursor` під час прогону одного або всіх правил. |
+
+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
+// eslint-disable-next-line n/no-process-exit, unicorn/no-process-exit -- standalone entry-point має повертати exit-code для CI/IDE
+```
+
+Це свідома відмова від загальної заборони `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.

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

@@ -0,0 +1,171 @@
+# lint.mjs — Security: TruffleHog filesystem scan
+
+## Огляд
+
+Файл `npm/rules/security/js/lint.mjs` реалізує CI-крок правила **security** для пошуку секретів у репозиторії. Це обгортка над зовнішнім інструментом [TruffleHog](https://github.com/trufflesecurity/trufflehog), яка запускає сканування всього робочого дерева (`filesystem` mode) і повертає його exit-код як результат лінтингу.
+
+Особливості:
+
+- **Repo-wide, а не per-file.** Модуль свідомо ігнорує перший аргумент `_files` — TruffleHog у режимі `filesystem` обробляє кореневу теку цілком і завжди сканує однаковий набір шляхів, незалежно від того, які саме файли передає рушій правил. Тому пер-файлового різновиду немає; результат однаковий для будь-якого підмножина файлів.
+- **Один прохід на сесію.** Сканер виконується синхронно через `spawnSync`, що відповідає правилу «без паралельних лінт-запусків» у монорепо.
+- **Контрактний інтерфейс.** Експорт `lint(files, cwd)` сумісний із загальним контрактом per-rule lint-функцій (`(files?, cwd?) => Promise<number>`), що дозволяє інтегрувати security-правило в загальний раннер однаково з іншими.
+
+Файл не має побічних ефектів на момент імпорту: запуск зовнішнього процесу відбувається лише при виклику `lint()`.
+
+## Експорти / API
+
+| Експорт | Тип                       | Призначення                                                                                             |
+| ------- | ------------------------- | ------------------------------------------------------------------------------------------------------- |
+| `lint`  | `function` (named export) | Запускає TruffleHog filesystem-скан із кореня `cwd` і повертає `Promise<number>` із exit-кодом процесу. |
+
+Default-експорту немає. Імпорт відбувається у вигляді:
+
+```js
+import { lint } from './lint.mjs'
+```
+
+## Функції
+
+### `lint(_files, cwd?)`
+
+**Сигнатура:**
+
+```js
+export function lint(_files, cwd = process.cwd()) => Promise<number>
+```
+
+**Параметри:**
+
+| Параметр | Тип                     | Обовʼязковий | За замовчанням  | Опис                                                                                                                                                             |
+| -------- | ----------------------- | ------------ | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `_files` | `string[] \| undefined` | ні           | —               | Список файлів від рушія правил. **Ігнорується**: TruffleHog у `filesystem`-режимі сканує дерево цілком. Префікс `_` у JSDoc сигналізує про навмисне ігнорування. |
+| `cwd`    | `string`                | ні           | `process.cwd()` | Робоча тека, у якій запускається TruffleHog. Сканування `.` виконуватиметься відносно неї.                                                                       |
+
+**Повертає:**
+
+`Promise<number>` — exit-код процесу TruffleHog:
+
+- `0` — секретів не знайдено (успіх).
+- Будь-яке інше число — або знайдено секрети, що відповідають критеріям `--results=verified,unknown` (через флаг `--fail`), або TruffleHog не зміг запуститись/упав.
+- `1` — fallback, який повертається, якщо `r.status` не є числом (наприклад, процес було вбито сигналом і `status === null`).
+
+**Side effects:**
+
+1. Запускає синхронний дочірній процес `trufflehog` через `node:child_process#spawnSync`.
+2. `stdio: 'inherit'` — stdout/stderr/stdin успадковуються з батьківського процесу; вивід TruffleHog потрапляє безпосередньо в консоль CI-runner.
+3. Блокує event loop до завершення процесу (`spawnSync` синхронний; результат лише обгортається у `Promise.resolve`).
+4. Не записує файли, не модифікує env, не змінює стан модуля.
+
+**Внутрішня механіка:**
+
+Викликається TruffleHog із набором аргументів:
+
+| Аргумент                     | Значення                                                                                                                         |
+| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| Команда                      | `trufflehog` (резолвиться через `PATH`)                                                                                          |
+| Subcommand                   | `filesystem`                                                                                                                     |
+| Шлях                         | `.` (відносно `cwd`)                                                                                                             |
+| `--no-update`                | Не намагатися автооновити сам TruffleHog у CI.                                                                                   |
+| `--exclude-paths`            | `.trufflehog-exclude` — файл зі шляхами/патернами, які виключити зі сканування. Має лежати в `cwd`.                              |
+| `--results=verified,unknown` | Звітувати лише **верифіковані** секрети та секрети **невідомого** статусу верифікації (відсікти `unverified`, щоб зменшити шум). |
+| `--fail`                     | Завершуватись із ненульовим exit-кодом, якщо знайдено результати, що відповідають фільтру вище.                                  |
+
+Параметри `spawnSync`:
+
+- `cwd` — переданий або `process.cwd()`.
+- `stdio: 'inherit'` — прямий проброс I/O.
+
+Після завершення:
+
+```js
+return Promise.resolve(typeof r.status === 'number' ? r.status : 1)
+```
+
+— безпечна нормалізація: якщо `status` відсутній (наприклад, процес перерваний сигналом → `r.status === null`, `r.signal === 'SIGTERM'`), функція повертає `1` як індикатор помилки.
+
+**Контрактні нотатки:**
+
+- Функція **не кидає виключення** для звичайних випадків (TruffleHog знайшов секрети або не запустився) — все нормалізується в exit-код через `Promise.resolve`. Якщо `spawnSync` сам кине синхронне виключення (наприклад, ENOENT через відсутність бінарника та некоректну поведінку runtime), воно пробʼється вгору — але стандартна поведінка Node для відсутнього виконуваного файлу — повернути `r.error`, а `r.status === null`, тому функція дасть `1`.
+- Поверне `Promise`, навіть якщо все відбулось синхронно — це потрібно для уніфікованого `await` у виклику з рушія правил.
+
+## Залежності
+
+### Зовнішні (npm) бібліотеки
+
+Жодних — модуль не імпортує сторонні пакети.
+
+### Стандартна бібліотека Node.js
+
+- **`node:child_process`** — використовується `spawnSync` для синхронного запуску `trufflehog`. Імпорт із префіксом `node:` обовʼязковий за правилами проекту.
+
+### Системні залежності
+
+- **`trufflehog`** (бінарник) — має бути доступний у `PATH` середовища, де запускається CI-крок. Інакше `spawnSync` поверне об'єкт із `error` (ENOENT) та `status === null`, і функція віддасть `1`.
+- **Файл `.trufflehog-exclude`** — очікується у корені `cwd`. Це plaintext-файл із патернами шляхів для виключення (формат TruffleHog `--exclude-paths`). Якщо файл відсутній, TruffleHog може завершитись із ненульовим кодом — це теж буде повернуто як exit-код.
+
+### Внутрішні модулі
+
+- Зовнішніх внутрішньопроєктних імпортів модуль не має. Він самодостатній і викликається рушієм правил security (`npm/rules/security/...`), який інтегрує його у загальний lint-пайплайн.
+
+## Потік виконання / Використання
+
+### Загальний потік
+
+1. Рушій правил (npm-пакет, що оркеструє лінтери) виявляє правило `security` для активного workspace.
+2. Викликає `lint(files, cwd)` із `files` (списком змінених/вибраних файлів) та `cwd` (коренем workspace або репо).
+3. `lint`:
+   - Ігнорує `files`.
+   - Викликає `spawnSync('trufflehog', [...], { cwd, stdio: 'inherit' })`.
+   - Користувач/CI бачить весь stdout/stderr TruffleHog у реальному часі.
+   - Після завершення процесу повертає `Promise<exitCode>`.
+4. Рушій правил агрегує exit-коди всіх лінтерів і визначає загальний результат (зазвичай: будь-яке ненульове значення = провал CI).
+
+### Типовий виклик з коду
+
+```js
+import { lint } from './lint.mjs'
+
+const exitCode = await lint(undefined, process.cwd())
+if (exitCode !== 0) {
+  console.error('[security] TruffleHog знайшов секрети або не зміг виконатись')
+  process.exitCode = exitCode
+}
+```
+
+### CI-сценарій
+
+1. CI-runner клонує репозиторій і встановлює бінарник `trufflehog` (через apt/brew/curl/прекомпільований release).
+2. Запускається `n-cursor lint` (або еквівалент), який обходить правила.
+3. Для правила `security` рушій кличе цю `lint`-функцію.
+4. TruffleHog рекурсивно сканує всі файли під `cwd`, окрім перелічених у `.trufflehog-exclude`.
+5. Якщо знайдено **верифіковані** або **unknown**-секрети — повертається ненульовий exit-код, флаг `--fail` гарантує цю поведінку.
+6. CI завершується із помилкою, кроки нижче не виконуються.
+
+### Граничні випадки
+
+| Ситуація                        | Поведінка                                                                                                                                                                   |
+| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `trufflehog` відсутній у `PATH` | `spawnSync` повертає `r.status === null`, функція віддає `1`. У stderr (через `inherit`) може зʼявитись повідомлення Node про відсутність бінарника, залежно від платформи. |
+| `.trufflehog-exclude` відсутній | TruffleHog зазвичай помиляється з ненульовим кодом — функція поверне його як є.                                                                                             |
+| Процес вбито сигналом           | `r.status === null` → повертається `1`.                                                                                                                                     |
+| Секретів немає                  | TruffleHog повертає `0` → функція повертає `0`.                                                                                                                             |
+| Передано `files=[...]`          | Аргумент проігноровано; сканування все одно зачіпає всю теку `cwd`.                                                                                                         |
+| `cwd` не вказано                | Використовується `process.cwd()` поточного Node-процесу.                                                                                                                    |
+
+### Конфігураційні «крутилки»
+
+Самі прапори зашиті в код і не параметризуються через аргументи функції. Якщо потрібно змінити поведінку (інший шлях `--exclude-paths`, інші типи результатів, увімкнути `--update`), правки робляться безпосередньо в `lint.mjs` — це навмисно, щоб уніфіковано тримати security-політику для всього монорепо.
+
+## Rebuild Test
+
+Перевірка контракту (для майбутніх refactor-ів — поведінка має зберігатись):
+
+1. **Експорт** named `lint` присутній; default-експорту немає.
+2. **Сигнатура** `lint(_files, cwd = process.cwd())` повертає `Promise<number>`.
+3. **Викликана команда** — рівно `trufflehog` із аргументами у точному порядку:
+   `filesystem`, `.`, `--no-update`, `--exclude-paths`, `.trufflehog-exclude`, `--results=verified,unknown`, `--fail`.
+4. **Options** для `spawnSync`: `{ cwd, stdio: 'inherit' }`.
+5. **Нормалізація exit-коду**: число → пробрасується; не число → `1`.
+6. **`_files` ігнорується** — наявність/відсутність/вміст не змінює викликаних аргументів TruffleHog.
+7. **Імпорт `child_process`** — лише через `node:`-префікс.
+8. **Жодних побічних ефектів на імпорті** — `lint` запускає процес лише при виклику.