@nitra/cursor 12.6.0 → 12.7.0

package/scripts/lib/docs/gha-workflow.md

@@ -3,328 +3,36 @@ type: JS Module
 title: gha-workflow.mjs
 resource: npm/scripts/lib/gha-workflow.mjs
 docgen:
-  crc: 266986bf
+  crc: d73b42f2
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
 ---
 
-Модуль `gha-workflow.mjs` — це набір допоміжних чистих функцій для **структурного аналізу GitHub Actions workflow-файлів** (`.yml`) після їх розбору як YAML.
+Надає функції для структурного аналізу конфігурацій GitHub Actions workflow (`.yml`). Дозволяє парсити YAML, витягувати значення з кроків, зокрема `uses:` та `run:`, а також перевіряти відповідність структури workflow певним вимогам. Це забезпечує цілеспрямований аналіз конфігурацій, замінюючи пошук підрядків у сирому тексті.
 
-Призначення модуля — замінити крихкий пошук підрядків у сирому тексті workflow-файла на **типобезпечну** перевірку значень `uses:` та `run:` у кроках (`steps`) робіт (`jobs`). Модуль використовується сценаріями перевірки (checkers) проєктних правил:
+## Поведінка
 
-- `check-ga` — загальна перевірка GitHub Actions workflows;
-- `check-js-lint` — перевірка структури `lint-js.yml`;
-- `check-text` — перевірка наявності викликів `bun run lint-text` у CI;
-- `check-style-lint` — перевірка викликів стайл-лінту в CI;
-- `check-npm-module` — перевірка workflow npm-модуля.
+parseWorkflowYaml парсить вміст workflow YAML у об'єкт, повертаючи `null` у разі синтаксичної помилки.
+flattenWorkflowSteps збирає плоский список усіх кроків з усіх job'ів workflow, додаючи метадані про job та індекс кроку.
+getStepUses отримує значення `uses` для заданого кроку.
+getStepRun отримує текст команди з поля `run` заданого кроку, об'єднуючи багаторядкові значення.
+eventPathsIncludeExact перевіряє, чи містить `on.push.paths` або `on.pull_request.paths` точне значення шляху.
+verifyLintJsWorkflowStructure перевіряє структуру workflow для відповідності вимогам, зокрема наявність `actions/checkout@v6` з `persist-credentials: false`, використання `setup-bun-deps` та наявність команд `bunx oxlint`, `bunx eslint .`, `bunx jscpd .` у кроках `run`.
+anyRunStepIncludes перевіряє, чи містить хоча б один `run` будь-якого кроку підрядок, який вказує на певний інструмент.
 
-Крім перевірки значень `uses:` та `run:`, модуль уміє:
+## Публічний API
 
-- розпізнавати локальну composite-action `./.github/actions/setup-bun-deps`;
-- перевіряти, що `actions/checkout@v6` викликається з `with.persist-credentials: false`;
-- виявляти заборонені в CI прапорці `--fix` у викликах `oxlint` та `eslint`;
-- перевіряти включення точного `glob` у списки `on.push.paths` / `on.pull_request.paths`.
+parseWorkflowYaml — перетворює YAML-файл робочого процесу у структурований об'єкт; повертає `null` при помилці синтаксису.
+flattenWorkflowSteps — об'єднує всі кроки, визначені у всіх завданнях.
+getStepUses — отримує значення, вказане у полі `uses:` для кроку.
+getStepRun — отримує команду, яку виконує крок (може бути одним або багатьма рядками).
+eventPathsIncludeExact — визначає, чи містить список шляхів події (push або pull_request) точне збігання.
+verifyLintJsWorkflowStructure — перевіряє наявність необхідних компонентів у файлі `lint-js.yml` (наприклад, `checkout@v6`, `persist-credentials`, `setup-bun-deps`, виконання команд).
+anyRunStepIncludes — виявляє, чи містить будь-який рядок виконання (`run`) певний підрядок.
 
-Модуль виконує лише читання та обчислення — він **не змінює** жодних файлів і **не виконує** жодних команд. Поведінка детермінована й залежить тільки від переданих аргументів.
+## Гарантії поведінки
 
-## Експорти / API
-
-Усі експорти з модуля — це **named exports** (іменовані експорти), `default export` немає.
-
-| Експорт                                      | Тип      | Короткий опис                                                                            |
-| -------------------------------------------- | -------- | ---------------------------------------------------------------------------------------- |
-| `parseWorkflowYaml(content)`                 | function | Парсить YAML вміст у звичайний об’єкт; при помилці повертає `null`.                      |
-| `flattenWorkflowSteps(root)`                 | function | Збирає всі кроки з усіх jobs у плоский список з метаданими `{ jobId, stepIndex, step }`. |
-| `getStepUses(step)`                          | function | Повертає значення `uses:` кроку або порожній рядок.                                      |
-| `getStepRun(step)`                           | function | Повертає значення `run:` кроку (підтримує рядок та масив рядків).                        |
-| `eventPathsIncludeExact(root, event, exact)` | function | Перевіряє, чи містить `on.<event>.paths` точне значення glob.                            |
-| `verifyLintJsWorkflowStructure(root)`        | function | Виконує повний набір структурних перевірок для `lint-js.yml`.                            |
-| `anyRunStepIncludes(root, needle)`           | function | Перевіряє, чи містить будь-який `run` кроку заданий підрядок.                            |
-
-Внутрішні (неекспортовані) функції-помічники:
-
-- `workflowJobsEntries(root)` — повертає `[jobId, job][]`;
-- `workflowJobSteps(job)` — повертає масив об’єктних кроків job;
-- `hasCheckoutWithPersistCredentialsFalse(steps)` — перевіряє `checkout@v6` з `persist-credentials: false`;
-- `appendCiFixFlagFailures(failures, steps)` — додає у `failures` рядки про заборонені `--fix` у CI.
-
-Внутрішні константи модуля:
-
-- `CHECKOUT_V6_USES = 'actions/checkout@v6'` — очікувана дія checkout та її версія.
-- `LOCAL_SETUP_BUN_DEPS_MARKER = './.github/actions/setup-bun-deps'` — шлях до локальної composite-action для встановлення Bun-залежностей.
-- `BUNX_OXLINT_FIX_RE = /bunx\s+oxlint[^\n]*--fix/u` — регулярний вираз для виявлення `bunx oxlint ... --fix` в одному рядку.
-
-## Функції
-
-### `parseWorkflowYaml(content)`
-
-**Сигнатура:** `parseWorkflowYaml(content: string): Record<string, unknown> | null`
-
-**Параметри:**
-
-- `content` — рядок із вмістом workflow-файла `.yml`.
-
-**Повертає:**
-
-- розібраний YAML як звичайний об’єкт (`Record<string, unknown>`), якщо вміст парситься і має тип `object` та не є `null`;
-- `null` — якщо `yaml.parse` кинув виняток або результат не є об’єктом.
-
-**Side effects:** немає. Помилка парсингу мовчки перехоплюється `try/catch`.
-
-**Примітки:** ця функція безпечна для викликача — навіть на некоректному YAML вона не падає, а повертає `null`, що далі обробляється у `verifyLintJsWorkflowStructure` як спеціальний випадок.
-
----
-
-### `flattenWorkflowSteps(root)`
-
-**Сигнатура:** `flattenWorkflowSteps(root: Record<string, unknown>): { jobId: string, stepIndex: number, step: Record<string, unknown> }[]`
-
-**Параметри:**
-
-- `root` — корінь розібраного YAML (об’єкт із полем `jobs`).
-
-**Повертає:** плоский масив об’єктів, кожен з яких містить:
-
-- `jobId` — ім’я job (ключ у `jobs`);
-- `stepIndex` — порядковий номер кроку всередині `steps` цього job (починається з 0);
-- `step` — сам об’єкт кроку.
-
-**Side effects:** немає.
-
-**Алгоритм:** ітерує через `workflowJobsEntries(root)`, для кожного job отримує `workflowJobSteps(job)`, нумерує кроки за допомогою `Array.prototype.entries()` та пуш у акумулятор. Невалідні (необ’єктні) jobs та невалідні steps пропускаються.
-
----
-
-### `getStepUses(step)`
-
-**Сигнатура:** `getStepUses(step: Record<string, unknown>): string`
-
-**Параметри:**
-
-- `step` — об’єкт одного елемента масиву `steps`.
-
-**Повертає:** значення `step.uses`, якщо це рядок; інакше — порожній рядок `''`.
-
-**Side effects:** немає.
-
-**Призначення:** уніфікований доступ до значення `uses:` без перевірок типу у викликачів.
-
----
-
-### `getStepRun(step)`
-
-**Сигнатура:** `getStepRun(step: Record<string, unknown>): string`
-
-**Параметри:**
-
-- `step` — об’єкт одного елемента масиву `steps`.
-
-**Повертає:** текст команди `run:`:
-
-- якщо `step.run` — рядок, повертається як є;
-- якщо `step.run` — масив, кожен елемент конвертується через `String(...)` та з’єднується через `\n`;
-- інакше — `''`.
-
-**Side effects:** немає.
-
-**Примітки:** YAML дозволяє запис `run:` як багаторядкового скаляра (`|` / `>-`) або як масиву рядків. Функція нормалізує обидва випадки до одного `string`, який потім зручно перевіряти через `.includes(...)` або регулярним виразом.
-
----
-
-### `eventPathsIncludeExact(root, event, exact)`
-
-**Сигнатура:** `eventPathsIncludeExact(root: Record<string, unknown>, event: 'push' | 'pull_request', exact: string): boolean`
-
-**Параметри:**
-
-- `root` — корінь workflow;
-- `event` — ім’я ключа в `on`: `'push'` або `'pull_request'`;
-- `exact` — очікуваний рядок (glob), який має бути присутній у `paths`.
-
-**Повертає:** `true`, якщо у `root.on[event].paths` є масив і він містить точне значення `exact`. У всіх інших випадках (відсутній `on`, відсутній `event`, `paths` не масив тощо) — `false`.
-
-**Side effects:** немає.
-
-**Гарантії безпеки:** функція захищена від відсутніх та некоректних типів проміжних об’єктів, тому її можна викликати на будь-якому `root`, повернутому з `parseWorkflowYaml`.
-
----
-
-### `verifyLintJsWorkflowStructure(root)`
-
-**Сигнатура:** `verifyLintJsWorkflowStructure(root: Record<string, unknown> | null): { ok: boolean, failures: string[] }`
-
-**Параметри:**
-
-- `root` — корінь розібраного workflow або `null`, якщо парсинг не вдався.
-
-**Повертає:** об’єкт результату:
-
-- `{ ok: true, failures: [] }` — усі перевірки пройдено;
-- `{ ok: false, failures: [...] }` — список причин відмови у вигляді людинозрозумілих українських повідомлень.
-
-**Side effects:** немає.
-
-**Перевірки, які виконуються (у порядку додавання до `failures`):**
-
-1. Якщо `root === null` — повертається одразу `{ ok: false, failures: ['YAML не вдалося розібрати — перевір синтаксис workflow'] }`.
-2. У жодному кроці немає `uses:` з підрядком `'actions/checkout@v6'` → `'немає кроку uses: actions/checkout@v6'`.
-3. Серед кроків з `actions/checkout@v6` немає такого, що містить `with.persist-credentials === false` → `'checkout@v6 без with.persist-credentials: false'`.
-4. У жодному кроці немає `uses:` з підрядком `'./.github/actions/setup-bun-deps'` → `'немає uses: ./.github/actions/setup-bun-deps'`.
-5. У сумарному `run`-блобі немає `'bunx oxlint'` → `'у run немає bunx oxlint'`.
-6. У сумарному `run`-блобі немає `'bunx eslint .'` → `'у run немає bunx eslint .'`.
-7. У сумарному `run`-блобі немає `'bunx jscpd .'` → `'у run немає bunx jscpd .'`.
-8. Для кожного кроку, чий `run` матчиться `BUNX_OXLINT_FIX_RE`, додається `'у run є oxlint з --fix (у CI заборонено)'`.
-9. Для кожного кроку, чий `run` містить `'eslint --fix'`, додається `'у run є eslint --fix (у CI заборонено)'`.
-
-**Примітка:** «сумарний `run`-блоб» — це `flattenWorkflowSteps(root).map(s => getStepRun(s.step)).join('\n')`. Тобто перевірки 5–7 пасять, навіть якщо `bunx oxlint`, `bunx eslint .` та `bunx jscpd .` рознесені по різних кроках.
-
----
-
-### `anyRunStepIncludes(root, needle)`
-
-**Сигнатура:** `anyRunStepIncludes(root: Record<string, unknown>, needle: string): boolean`
-
-**Параметри:**
-
-- `root` — корінь workflow;
-- `needle` — підрядок для пошуку в текстах `run:`.
-
-**Повертає:** `true`, якщо знайдено принаймні один крок, у `run:` якого є `needle`; інакше `false`.
-
-**Side effects:** немає. Ітерація припиняється на першому збігу (рання передача).
-
-**Типовий приклад:** `anyRunStepIncludes(root, 'bun run lint-text')` для `check-text` — перевірити, що CI взагалі викликає таргет лінту текстів.
-
----
-
-### `workflowJobsEntries(root)` (internal)
-
-**Сигнатура:** `workflowJobsEntries(root: Record<string, unknown>): [string, Record<string, unknown>][]`
-
-**Параметри:** `root` — корінь workflow.
-
-**Повертає:** список пар `[jobId, job]` для тих ключів `jobs`, у яких значення є непорожнім об’єктом.
-
-**Side effects:** немає.
-
-**Алгоритм:** перевіряє наявність та тип `root.jobs`, далі `Object.entries(jobs).flatMap(...)` фільтрує невалідні значення (масив порожніх або одно-елементних масивів).
-
----
-
-### `workflowJobSteps(job)` (internal)
-
-**Сигнатура:** `workflowJobSteps(job: Record<string, unknown>): Record<string, unknown>[]`
-
-**Параметри:** `job` — один job-об’єкт.
-
-**Повертає:** масив об’єктних кроків з `job.steps`; невалідні (необ’єктні / `null`) елементи фільтруються.
-
-**Side effects:** немає.
-
----
-
-### `hasCheckoutWithPersistCredentialsFalse(steps)` (internal)
-
-**Сигнатура:** `hasCheckoutWithPersistCredentialsFalse(steps: { step: Record<string, unknown> }[]): boolean`
-
-**Параметри:** `steps` — результат `flattenWorkflowSteps` (використовується тільки поле `step`).
-
-**Повертає:** `true`, якщо знайдено крок, у якого:
-
-- `uses` містить `'actions/checkout@v6'`;
-- `step.with` — об’єкт;
-- `step.with['persist-credentials'] === false` (саме `false`, а не «фолсі»).
-
-**Side effects:** немає.
-
-**Призначення:** перевірити, що `actions/checkout@v6` явно вимкнув збереження токена в git-конфізі — це вимога безпеки в правилі `n-ga`.
-
----
-
-### `appendCiFixFlagFailures(failures, steps)` (internal)
-
-**Сигнатура:** `appendCiFixFlagFailures(failures: string[], steps: { step: Record<string, unknown> }[]): void`
-
-**Параметри:**
-
-- `failures` — акумулятор-масив, у який функція **пушить** нові рядки помилок;
-- `steps` — результат `flattenWorkflowSteps`.
-
-**Повертає:** `undefined` (мутує `failures`).
-
-**Side effects:** мутація переданого масиву `failures` через `Array.prototype.push`.
-
-**Логіка:** для кожного кроку:
-
-- якщо `BUNX_OXLINT_FIX_RE.test(run)` — додає повідомлення про заборонений `--fix` у `bunx oxlint`;
-- якщо `run.includes('eslint --fix')` — додає повідомлення про заборонений `eslint --fix`.
-
-**Примітка:** функція може додати **обидва** повідомлення для одного і того ж кроку, якщо в `run` присутні обидва патерни. Якщо в різних кроках присутній один і той самий патерн — повідомлення додасться **кілька разів** (по одному на крок).
-
-## Залежності
-
-**Зовнішні npm-пакети:**
-
-- `yaml` — функція `parse(content)` для розбору YAML у JS-об’єкт. Імпорт іменований: `import { parse } from 'yaml'`.
-
-**Стандартна бібліотека JS:** `Object.entries`, `Array.isArray`, `Array.prototype.flatMap`, `Array.prototype.map`, `Array.prototype.entries`, `Array.prototype.some`, `Array.prototype.includes`, `Array.prototype.join`, `RegExp.prototype.test`, `String.prototype.includes`.
-
-**Внутрішні залежності проєкту:** жодних модулів проєкту не імпортує — це листовий хелпер.
-
-**Хто залежить від цього модуля (зворотні залежності):** згідно з docstring файла — скрипти `check-ga`, `check-js-lint`, `check-text`, `check-style-lint`, `check-npm-module`. Конкретні шляхи до цих скриптів живуть у `npm/scripts/` / `npm/checks/` та використовують іменовані експорти модуля.
-
-## Потік виконання / Використання
-
-### Типовий цикл використання сценарієм-checker
-
-1. Сценарій читає вміст файла `.github/workflows/<name>.yml` як рядок (наприклад через `node:fs/promises`).
-2. Викликає `const root = parseWorkflowYaml(content)`.
-3. Якщо `root === null` — повідомляє про синтаксичну помилку YAML.
-4. Інакше викликає одну зі спеціалізованих перевірок (наприклад `verifyLintJsWorkflowStructure(root)`) або серію загальних (`flattenWorkflowSteps`, `getStepUses`, `getStepRun`, `anyRunStepIncludes`, `eventPathsIncludeExact`).
-5. На основі результату формує звіт перевірки.
-
-### Приклад: перевірка `lint-js.yml`
-
-```js
-import { readFile } from 'node:fs/promises'
-import { parseWorkflowYaml, verifyLintJsWorkflowStructure } from './gha-workflow.mjs'
-
-const content = await readFile('.github/workflows/lint-js.yml', 'utf8')
-const root = parseWorkflowYaml(content)
-const result = verifyLintJsWorkflowStructure(root)
-
-if (!result.ok) {
-  for (const f of result.failures) {
-    console.error('lint-js.yml:', f)
-  }
-  process.exit(1)
-}
-```
-
-### Приклад: перевірка наявності таргета `bun run lint-text`
-
-```js
-import { parseWorkflowYaml, anyRunStepIncludes } from './gha-workflow.mjs'
-
-const root = parseWorkflowYaml(content)
-if (root && !anyRunStepIncludes(root, 'bun run lint-text')) {
-  console.error('у CI відсутній виклик bun run lint-text')
-}
-```
-
-### Приклад: перевірка `on.pull_request.paths`
-
-```js
-import { parseWorkflowYaml, eventPathsIncludeExact } from './gha-workflow.mjs'
-
-const root = parseWorkflowYaml(content)
-if (root && !eventPathsIncludeExact(root, 'pull_request', '**/*.vue')) {
-  console.error('on.pull_request.paths не містить **/*.vue')
-}
-```
-
-### Властивості, корисні викликачам
-
-- **Чисті функції.** Жодних бічних ефектів (крім явної мутації `failures` в `appendCiFixFlagFailures`, яка інкапсульована всередині `verifyLintJsWorkflowStructure`).
-- **Безпечність до помилок типів.** Усі публічні функції захищені від некоректних або відсутніх ключів — повертають `''`, `false` або `[]` замість падіння.
-- **Уніфікований доступ.** `getStepUses` та `getStepRun` нормалізують форму YAML (рядок vs масив), щоб викликач завжди працював із `string`.
-- **Точне `paths`-зіставлення.** `eventPathsIncludeExact` вимагає **точного** елемента масиву, а не підрядка — тому glob-патерни мають бути записані як є.
-- **Сумарний `run`-блоб.** У `verifyLintJsWorkflowStructure` пункти 5–7 не вимагають, щоб усі команди жили в одному `run`-кроці — вони можуть бути рознесені по кроках/jobs.
+- Read-only: не виконує операцій запису (ФС/БД).
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).
+- За певних помилок повертає порожнє значення (напр. `null`) замість винятку.
+- Свідомо пропускає шляхи: `.github`, `.git`.

package/scripts/lib/docs/index.md

@@ -31,6 +31,7 @@ resource: npm/scripts/lib/
 | [rule-predicates.mjs](rule-predicates.md) | JS Module |
 | [run-conftest-batch.mjs](run-conftest-batch.md) | JS Module |
 | [run-lint-step.mjs](run-lint-step.md) | JS Module |
+| [run-lint.mjs](run-lint.md) | JS Module |
 | [run-rule-cli.mjs](run-rule-cli.md) | JS Module |
 | [run-rule.mjs](run-rule.md) | JS Module |
 | [run-standard-lint.mjs](run-standard-lint.md) | JS Module |

package/scripts/lib/docs/list-project-rules-mdc.md

@@ -3,12 +3,14 @@ type: JS Module
 title: list-project-rules-mdc.mjs
 resource: npm/scripts/lib/list-project-rules-mdc.mjs
 docgen:
-  crc: e17e0855
+  crc: 60cd4e83
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 100
 ---
 
-Експортує константу CURSOR_RULES_DIR, яка вказує на каталог правил у проєкті-споживачі. Надає функцію для отримання відсортованого списку всіх файлів правил `.mdc` з цього каталогу.
+## Огляд
+
+Цей модуль визначає шлях до `.mdc`-файлів правил у проєкті-споживачі, що зберігаються у директорії, вказаній константою CURSOR_RULES_DIR. Він надає відсортований список імен цих файлів. Це винесення логіки з `bin/n-cursor.js` забезпечує розділення відповідальності між інструментом командного рядка та функцією перевірки конформності.
 
 ## Поведінка
 
@@ -22,5 +24,4 @@ listProjectRulesMdcFiles — Збирає список файлів MDC, що м
 
 ## Гарантії поведінки
 
-- Read-only: файл не виконує операцій запису у файлову систему.
-- Не звертається до мережі.
+- Read-only: не виконує операцій запису (ФС/БД).

package/scripts/lib/docs/list-rule-ids.md

@@ -3,158 +3,25 @@ type: JS Module
 title: list-rule-ids.mjs
 resource: npm/scripts/lib/list-rule-ids.mjs
 docgen:
-  crc: 5ef1ead5
+  crc: d8b3ea73
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
 ---
 
-Модуль `list-rule-ids.mjs` — невелика бібліотечна утиліта, призначена для перебору директорій-правил у каталозі `npm/rules/` та повернення відсортованого алфавітно списку ідентифікаторів правил, які реально містять виконуваний модуль `fix.mjs`.
+## Огляд
 
-Логіка модуля побудована навколо архітектурної інваріанти проєкту: після так званої «атомарної міграції» кожне валідне правило **зобов'язане** мати файл `fix.mjs` у власній директорії `rules/<id>/`. Будь-яка піддиректорія без `fix.mjs` вважається або «не-правилом» (службова тека), або заглушкою-чернеткою — і ігнорується. Прихованих директорій (імена, що починаються з `.`) також не існує в результаті.
+Перебирає директорії у `rules/` та фільтрує їх, вибираючи лише ті, що містять єдиний канонічний entrypoint (`rules/<id>/main.mjs`), згідно з ADR 2026-06-21. Функція повертає список ідентифікаторів правил, які відповідають цьому канону. Операція є лише для читання файлової системи.
 
-Додатково модуль підтримує опційне точкове фільтрування одним конкретним `id`, що використовується CLI-флагом `--rule abie` для прогону команд у режимі «тільки одне правило».
+## Поведінка
 
-Модуль повністю асинхронний (використовує `node:fs/promises`), не має зовнішніх npm-залежностей і не виконує жодних побічних ефектів окрім читання директорії та перевірки наявності файлу через `existsSync`.
+1. Зчитує список усіх каталогів у директорії, що містить правила.
+2. Фільтрує цей список, залишаючи лише каталоги, які не починаються з крапки.
+3. Для кожного каталогу перевіряє, чи існує у ньому файл `main.mjs`.
+4. Фільтрує список, залишаючи лише ті каталоги, які містять файл `main.mjs`.
+5. Якщо надано фільтр, додатково фільтрує список, залишаючи лише той ID, що збігається з фільтром.
+6. Сортує отримані ID в алфавітному порядку.
+7. Повертає відсортований список ID правил.
 
-## Експорти / API
+## Гарантії поведінки
 
-Файл експортує одну іменовану функцію:
-
-| Експорт       | Тип              | Призначення                                                                                                                       |
-| ------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------- |
-| `listRuleIds` | `async function` | Повертає `Promise<string[]>` зі списком id правил, відфільтрованим за наявністю `fix.mjs` і опційним рівнянням до конкретного id. |
-
-Експорту за замовчуванням немає.
-
-## Функції
-
-### `listRuleIds(bundledRulesDir, filter)`
-
-#### Сигнатура
-
-```js
-export async function listRuleIds(bundledRulesDir, filter)
-```
-
-JSDoc-типи:
-
-```
-@param {string} bundledRulesDir — абсолютний шлях до `npm/rules/`
-@param {string} [filter]       — id одного правила (через `--rule abie`)
-@returns {Promise<string[]>}    — відсортовані алфавітно id
-```
-
-#### Параметри
-
-- **`bundledRulesDir`** (`string`, обовʼязковий) — абсолютний шлях до кореневої теки правил, найчастіше `npm/rules/` (наприклад, `/path/to/repo/npm/rules`). Передбачається, що шлях існує і є директорією; модуль не валідує його окремо — будь-яка помилка з `fs.readdir` пробрасується далі промісом.
-- **`filter`** (`string | undefined`, опційний) — точна назва правила, до якої потрібно звузити список. Якщо параметр не передано (`undefined`), повертаються всі знайдені id. Якщо передано, у результат потрапляють лише ті id, що _точно_ рівні `filter`. Часткові збіги, регулярні вирази або кейс-незалежність не підтримуються.
-
-#### Повертає
-
-`Promise<string[]>` — масив рядків-ідентифікаторів правил, відсортованих алфавітно за допомогою `Array.prototype.toSorted` із компаратором `a.localeCompare(b)`. Сортування _стабільне_ для оригінального методу і коректне для Unicode-локалей.
-
-Можливі сценарії результату:
-
-- Порожній масив `[]` — якщо в `bundledRulesDir` немає жодної директорії з `fix.mjs`, або якщо `filter` не збігається з жодним наявним id.
-- Масив з одного елемента — типово при заданому `filter`.
-- Повний відсортований список усіх правил — у випадку відсутності `filter`.
-
-#### Алгоритм / послідовність кроків
-
-1. Викликається `readdir(bundledRulesDir, { withFileTypes: true })` — отримуємо масив `Dirent`-обʼєктів (а не просто рядків імен), що дає змогу одразу перевіряти тип запису без додаткових `stat`-викликів.
-2. Залишаються лише записи, для яких одночасно:
-   - `e.isDirectory()` — це саме директорія;
-   - `!e.name.startsWith('.')` — імʼя не починається з крапки (відсікаються приховані теки на кшталт `.git`, `.cache`, тощо).
-3. Записи перетворюються на голі імена (`.map(e => e.name)`).
-4. Фільтрація на наявність `fix.mjs` — для кожного `id` синхронно перевіряється `existsSync(join(bundledRulesDir, id, 'fix.mjs'))`. Директорії без цього файлу відсіюються як «not-a-rule або заглушка».
-5. Фільтрація за `filter` — якщо параметр визначений, залишаються лише id, рівні `filter`; інакше пропускаються всі.
-6. Сортування `toSorted((a, b) => a.localeCompare(b))` — повертає новий масив без мутації проміжного.
-
-#### Side effects
-
-- **Дискові читання**: `readdir` (асинхронний обхід директорії) та `existsSync` (синхронні перевірки наявності файлу для кожного кандидата). Винятки I/O пробрасуються відхиленим промісом.
-- **Жодних записів, мережевих викликів, мутацій глобального стану, логування** — функція є read-only і чистою щодо побічних ефектів окрім згаданих читань ФС.
-- Використання `existsSync` у циклі — це _синхронні_ виклики всередині асинхронної функції; вони виконуються послідовно, але без `await`. Для типового розміру каталогу `npm/rules/` (десятки правил) це непомітна вартість.
-
-#### Гранітні випадки
-
-- Якщо `bundledRulesDir` не існує — `readdir` відхиляє проміс з `ENOENT`.
-- Якщо в директорії є символічні посилання — поведінка залежить від того, що повертає `Dirent.isDirectory()`; ця функція покладається на штатну семантику Node.js.
-- Якщо `filter` переданий як порожній рядок `''` — він _не_ є `undefined`, тому фільтр буде застосовано (`id === ''`), і результат майже напевно буде порожнім.
-- Файл `fix.mjs` як директорія: малоймовірний випадок, але `existsSync` поверне `true` для будь-якого існуючого запису з цим імʼям; модуль не розрізняє файл і теку.
-
-## Залежності
-
-### Вбудовані модулі Node.js
-
-| Модуль             | Імпортований символ | Використання                                                 |
-| ------------------ | ------------------- | ------------------------------------------------------------ |
-| `node:fs`          | `existsSync`        | Синхронна перевірка наявності `fix.mjs` у кожному кандидаті. |
-| `node:fs/promises` | `readdir`           | Асинхронний обхід `bundledRulesDir` з `withFileTypes: true`. |
-| `node:path`        | `join`              | Безпечне зʼєднання сегментів шляху до `fix.mjs`.             |
-
-### Зовнішні npm-залежності
-
-Немає.
-
-### Внутрішні залежності
-
-Файл не імпортує жодних інших модулів проєкту. Сам по собі він використовується як бібліотечна функція з інших скриптів у `npm/scripts/` (CLI-обгортки, які приймають флаг `--rule`).
-
-## Потік виконання / Використання
-
-### Контекст у проєкті
-
-`listRuleIds` — це фундамент будь-якого скрипту, який «робить щось для кожного правила»: лінт, авто-фікс, генерація звіту, перевірка покриття, нормалізація ADR тощо. Замість того щоб кожному скрипту самостійно перелічувати теки в `npm/rules/`, всі вони викликають цю функцію та отримують однаковий, відсортований, відфільтрований список — це гарантує детермінованість порядку обробки правил.
-
-Архітектурно файл підкріплює інваріант «`fix.mjs` обовʼязковий»: будь-яка тека без нього автоматично невидима для всіх споживачів. Це дає змогу тримати у `rules/` допоміжні підтеки (наприклад, шаблони, шаред-файли) без ризику, що вони будуть оброблені як правило.
-
-### Приклад використання
-
-```js
-import { listRuleIds } from './lib/list-rule-ids.mjs'
-import { resolve } from 'node:path'
-
-const bundledRulesDir = resolve(import.meta.dirname, '../../rules')
-
-// 1. Всі правила.
-const all = await listRuleIds(bundledRulesDir)
-// → ['abie', 'changelog', 'feedback', ...]
-
-// 2. Тільки одне правило (з CLI-флагу --rule abie).
-const ruleFlag = process.argv.includes('--rule') ? process.argv[process.argv.indexOf('--rule') + 1] : undefined
-
-const subset = await listRuleIds(bundledRulesDir, ruleFlag)
-// → ['abie']  якщо ruleFlag === 'abie' і таке правило існує
-// → []        якщо ruleFlag не відповідає жодному правилу
-```
-
-### Інтеграція з CLI
-
-Типовий патерн виклику в скриптах проєкту:
-
-1. Скрипт парсить `process.argv` (часто через `mri`/`minimist` або вручну), отримує опційний `--rule <id>`.
-2. Викликає `listRuleIds(rulesDir, ruleFromArgv)` і чекає на результат.
-3. Ітерується по отриманому масиву і виконує цільову дію (fix/check/коверідж) для кожного id.
-
-### Послідовність виконання при виклику
-
-```
-listRuleIds(dir, filter)
-   │
-   ├─ readdir(dir, withFileTypes:true) ── async ──▶ [Dirent...]
-   │
-   ├─ .filter(isDirectory && !startsWith('.'))
-   ├─ .map(e => e.name)
-   ├─ .filter(existsSync(<id>/fix.mjs))      ◀── sync I/O loop
-   ├─ .filter(filter === undefined || id === filter)
-   ├─ .toSorted(localeCompare)
-   │
-   ▼
-Promise<string[]>  (відсортовані id)
-```
-
-### Очікувані помилки
-
-- `ENOENT` / `ENOTDIR` від `readdir` — якщо переданий `bundledRulesDir` неіснуючий або не є директорією. Викликач має або переконатися в коректності шляху перед викликом, або обгорнути виклик у `try/catch`.
-- `EACCES` — якщо немає прав на читання теки.
-
-Усі інші помилки (відсутність окремого `fix.mjs`, відсутність відповідності `filter`) семантично не є помилками — вони лише звужують повернений масив.
+- Read-only: не виконує операцій запису (ФС/БД).

package/scripts/lib/docs/read-n-cursor-config-lite.md

@@ -3,30 +3,26 @@ type: JS Module
 title: read-n-cursor-config-lite.mjs
 resource: npm/scripts/lib/read-n-cursor-config-lite.mjs
 docgen:
-  crc: a5fb0592
+  crc: a38ac2f4
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
 ---
 
-Цей файл читає файл `.n-cursor.json`, що містить список правил для конфігурації. Він повертає цей список, щоб `fix.mjs` міг використовувати правила для визначення конфігурації. Це забезпечує базове читання конфігурації правил для запуску `fix.mjs` з командного рядка.
+## Огляд
 
-## Поведінка
+Модуль надає легкий, лише для читання, інтерфейс для парсингу конфігурації `.n-cursor.json`. Він призначений для ізольованих, окремих викликів `check.mjs`. Модуль визначає стан кожного правила, ґрунтуючись на вмісті `.n-cursor.json`. Якщо файл відсутній, правило вважається активним (поведінка "open by default"). Якщо файл присутній, стан правила залежить від списків `rules` та `disableRules` у конфігурації. Модуль повертає об'єкт, що містить списки активних та вимкнених правил.
 
-**readNCursorConfigLite**
-Зчитує конфігурацію з файлу `.n-cursor.json`. Повертає об'єкт з інформацією про правила та вимкнені правила. Якщо файл відсутній, повертає конфігурацію з порожнім масивом правил.
+## Поведінка
 
-**isRuleEnabled**
-Перевіряє, чи правило з активним статусом згідно з конфігурацією. Повертає `true`, якщо файл відсутній, правило вимкнено в `disable-rules` або присутнє в `rules`. Повертає `false` в іншому випадку.
+Поведінка
+readNCursorConfigLite читає конфігураційний файл .n-cursor.json у вказаному каталозі, повертаючи стан його існування та списки дозволених і вимкнених правил.
+isRuleEnabled визначає, чи має бути виконане правило, виходячи зі стану конфігураційного файлу та ID правила.
 
 ## Публічний API
 
-- readNCursorConfigLite — Завантажує конфігурацію курсора.
-- isRuleEnabled — Перевіряє статус активності правила.
+readNCursorConfigLite — зчитує базові налаштування курсора з конфігурації.
+isRuleEnabled — визначає, чи діє певне правило на основі конфігурації. Якщо конфігурація відсутня, правило вважається активним за замовчуванням. Якщо правило явно вимкнено, воно не діє. Якщо правило визначено у списку правил, воно діє. В іншому випадку, правило не діє.
 
 ## Гарантії поведінки
 
-- Якщо файл `.n-cursor.json` відсутній, вважається, що всі правила включені.
-- Якщо файл `.n-cursor.json` існує, але поле `rules` порожнє, вважається, що всі правила включені.
-- Якщо файл `.n-cursor.json` існує і має поле `rules`, але поле `rules` порожнє, вважається, що всі правила включені.
-- Якщо правило вказане в полі `disable-rules`, воно вимкнено.
-- Повертає `false` якщо файл `.n-cursor.json` відсутній або недійсний.
-- Повертає `null` якщо не вдалося прочитати файл `.n-cursor.json`.
-- Не використовує кешування.
+- Read-only: не виконує операцій запису (ФС/БД).