@nitra/cursor 12.6.1 → 12.7.0

package/rules/release/docs/release.md

@@ -6,11 +6,8 @@ docgen:
   crc: 06d3556b
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 100
-  judgeModel: openai-codex/gpt-5.4-mini
 ---
 
-## Огляд
-
 Файл автоматизує процес випуску версій. Він агрегує зміна-файли для всіх робочих просторів у `version-bump` та `CHANGELOG`, комітить зміни, ставить тег `<name>@<version>` та видаляє використані зміна-файли. Цей процес виконується у CI на гілці `main` (n-cursor-release-design, варіант A). Публічні функції, що надає модуль, — `release` та `runReleaseCli`.
 
 ## Поведінка

package/rules/release/release.mdc

@@ -0,0 +1,10 @@
+---
+description: n-cursor release та n-cursor change — автоматичний version-bump і CHANGELOG із change-файлів
+version: '1.0'
+globs: "**/package.json,**/pyproject.toml,**/CHANGELOG.md,**/.changes/*.md"
+alwaysApply: false
+---
+
+Версія та CHANGELOG **не редагуються вручну**. Єдиний артефакт зміни — **change-файл** (`npx @nitra/cursor change --bump <major|minor|patch> --section <Added|Changed|Fixed|Removed> --message "<…>"`). Bump `version` і генерацію секції CHANGELOG виконує `n-cursor release` у CI на `main`.
+
+Детальна модель (база порівняння, формат CHANGELOG, post-release-інваріант) — у `n-changelog.mdc`.

package/rules/rust/docs/index.md

@@ -9,3 +9,4 @@ resource: npm/rules/rust/
 | Файл | Тип |
 |---|---|
 | [fix.mjs](fix.md) | JS Module |
+| [main.mjs](main.md) | JS Module |

package/rules/rust/docs/main.md

@@ -0,0 +1,27 @@
+---
+type: JS Module
+title: main.mjs
+resource: npm/rules/rust/main.mjs
+docgen:
+  crc: a3060168
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 90
+---
+
+## Огляд
+
+Модуль надає функції для роботи з кодом Rust. Функція `run` виконує повний аналіз коду, включаючи перевірку відповідності політиці MDC. Функція `lint` здійснює статичний аналіз коду. Обидві функції можуть ініціювати форматування та аналіз за допомогою `cargo`.
+
+## Поведінка
+
+run виконує перевірку коду Rust, застосовуючи політику та посилання MDC.
+lint запускає оркестрацію перевірки Rust, виконуючи `rustfmt` та `clippy` через `cargo`.
+
+## Публічний API
+
+run — точка входу для виконання правила, що перевіряє логіку, пов'язану з JS-зацікавленостями, політикою та посиланнями MDC.
+lint — точка входу для запуску лінтера Rust-коду.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).

package/rules/rust/{js/lint.mjs → main.mjs}

@@ -3,9 +3,21 @@ import { spawnSync } from 'node:child_process'
 import { existsSync } from 'node:fs'
 import { join } from 'node:path'
 
-import { createCheckReporter } from '../../../scripts/lib/check-reporter.mjs'
-import { runStandardLint } from '../../../scripts/lib/run-standard-lint.mjs'
-import { resolveCmd } from '../../../scripts/utils/resolve-cmd.mjs'
+import { createCheckReporter } from '../../scripts/lib/check-reporter.mjs'
+import { runStandardLint } from '../../scripts/lib/run-standard-lint.mjs'
+import { resolveCmd } from '../../scripts/utils/resolve-cmd.mjs'
+import { isRunAsCli, runRuleCli } from '../../scripts/lib/run-rule-cli.mjs'
+import { runStandardRule } from '../../scripts/lib/run-standard-rule.mjs'
+
+/**
+ * Єдиний entrypoint правила (ADR 2026-06-21). `run()` — check-поверхня (applies → JS-concerns
+ * → policy → mdc-refs); `lint()` нижче — lint-поверхня (cargo fmt/clippy), імпл інлайн тут.
+ * @param {import('../../scripts/lib/run-standard-rule.mjs').RuleContext} [ctx] контекст прогону
+ * @returns {Promise<number>} 0 — OK, 1 — порушення
+ */
+export function run(ctx) {
+  return runStandardRule(import.meta.dirname, ctx)
+}
 
 /**
  * Запускає cargo-крок і репортить результат.
@@ -77,3 +89,8 @@ function runRustLint(cwd = process.cwd(), opts = {}) {
 export function lint(_files, cwd = process.cwd(), opts = {}) {
   return runStandardLint(import.meta.dirname, () => runRustLint(cwd, opts))
 }
+
+if (isRunAsCli(import.meta.url)) {
+  // Standalone: bun rules/rust/main.mjs — повний еквівалент `npx @nitra/cursor check rust`.
+  process.exitCode = await runRuleCli(import.meta.dirname)
+}

package/rules/security/docs/index.md

@@ -9,3 +9,4 @@ resource: npm/rules/security/
 | Файл | Тип |
 |---|---|
 | [fix.mjs](fix.md) | JS Module |
+| [main.mjs](main.md) | JS Module |

package/rules/security/docs/main.md

@@ -0,0 +1,28 @@
+---
+type: JS Module
+title: main.mjs
+resource: npm/rules/security/main.mjs
+docgen:
+  crc: a0730dcb
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+---
+
+## Огляд
+
+Модуль виконує перевірку якості коду та безпеки репозиторію, спираючись на конфігурації, визначені у meta.json. Функція `run` застосовує політики та посилання на MDC для виконання перевірки. Функція `lint` сканує файлову систему репозиторію на наявність секретів. Обидві функції мають публічний статус, а кешування відбувається у межах одного прогону.
+
+## Поведінка
+
+run виконує перевірку, застосовуючи політики та посилання на MDC.
+lint сканує файлову систему репозиторію на наявність секретів за допомогою trufflehog.
+
+## Публічний API
+
+run — Основна точка входу правила, що виконує перевірку: застосовує логіку, перевіряє аспекти JavaScript, застосовує політику та перевіряє посилання на MDC.
+lint — Сканує весь репозиторій на наявність секретів за допомогою trufflehog.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).
+- Кешує результати в межах одного прогону.

package/rules/security/main.mjs

@@ -0,0 +1,45 @@
+import { spawnSync } from 'node:child_process'
+
+import { isRunAsCli, runRuleCli } from '../../scripts/lib/run-rule-cli.mjs'
+import { runStandardRule } from '../../scripts/lib/run-standard-rule.mjs'
+
+/**
+ * Єдиний entrypoint правила (ADR 2026-06-21). `run()` — check-поверхня: applies →
+ * JS-concerns → policy → mdc-refs (через runStandardRule).
+ * Library mode: викликається CLI orchestration через `import + run(ctx)`.
+ * @param {import('../../scripts/lib/run-standard-rule.mjs').RuleContext} [ctx] контекст прогону (walkCache тощо)
+ * @returns {Promise<number>} 0 — OK, 1 — порушення
+ */
+export function run(ctx) {
+  return runStandardRule(import.meta.dirname, ctx)
+}
+
+/**
+ * `lint()` — lint-поверхня security: trufflehog filesystem скан усього репо (per-file немає).
+ * Викликається lint-оркестратором за `meta.json#lint`.
+ * @param {string[] | undefined} _files ігнорується (whole-repo скан)
+ * @param {string} [cwd] корінь
+ * @returns {Promise<number>} exit code (0 — секретів не знайдено)
+ */
+export function lint(_files, cwd = process.cwd()) {
+  const r = spawnSync(
+    'trufflehog',
+    [
+      'filesystem',
+      '.',
+      '--no-update',
+      '--exclude-paths',
+      '.trufflehog-exclude',
+      '--results=verified,unknown',
+      '--fail'
+    ],
+    { cwd, stdio: 'inherit' }
+  )
+  return Promise.resolve(typeof r.status === 'number' ? r.status : 1)
+}
+
+if (isRunAsCli(import.meta.url)) {
+  // Standalone: bun rules/<id>/main.mjs — повний еквівалент `npx @nitra/cursor check <id>`
+  // (config-loading + whitelist + summary): library-роль (run) + standalone-роль (CLI-блок).
+  process.exitCode = await runRuleCli(import.meta.dirname)
+}

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

@@ -9,3 +9,4 @@ resource: npm/rules/style-lint/
 | Файл | Тип |
 |---|---|
 | [fix.mjs](fix.md) | JS Module |
+| [main.mjs](main.md) | JS Module |

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

@@ -0,0 +1,29 @@
+---
+type: JS Module
+title: main.mjs
+resource: npm/rules/style-lint/main.mjs
+docgen:
+  crc: d4951ce5
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+---
+
+## Огляд
+
+Модуль реалізує логіку для виконання правил, фільтрації файлів за розширеннями та запуску стильового лінтера. Функція `run` виконує визначені правила. `filterStyleFiles` обробляє файли, вибираючи їх на основі розширень. `lint` запускає перевірку стилю.
+
+## Поведінка
+
+run виконує стандартну перевірку для правила.
+filterStyleFiles відбирає з наданого списку лише файли з розширеннями css, scss або vue.
+lint запускає stylelint для перевірки стильових файлів або всього проєкту.
+
+## Публічний API
+
+run — головна точка входу для виконання правил, що включає перевірку логіки застосування (JS-занепокложення → політика → посилання MDC) та перевірку стилів (stylelint для CSS/SCSS/Vue).
+filterStyleFiles — відбирає файли, що містять стилі для подальшої обробки.
+lint — виконує стилістичну перевірку (stylelint) для окремих файлів або всього проєкту.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).

package/rules/style-lint/{js/lint.mjs → main.mjs}

@@ -1,8 +1,20 @@
-/** @see ./docs/lint.md */
 import { spawnSync } from 'node:child_process'
 
+import { isRunAsCli, runRuleCli } from '../../scripts/lib/run-rule-cli.mjs'
+import { runStandardRule } from '../../scripts/lib/run-standard-rule.mjs'
+
 const STYLE_EXT_RE = /\.(?:css|scss|vue)$/u
 
+/**
+ * Єдиний entrypoint правила (ADR 2026-06-21). `run()` — check-поверхня (applies → JS-concerns
+ * → policy → mdc-refs); `lint()` — lint-поверхня (stylelint по css/scss/vue), імпл інлайн тут.
+ * @param {import('../../scripts/lib/run-standard-rule.mjs').RuleContext} [ctx] контекст прогону
+ * @returns {Promise<number>} 0 — OK, 1 — порушення
+ */
+export function run(ctx) {
+  return runStandardRule(import.meta.dirname, ctx)
+}
+
 /**
  * @param {string[]} files список шляхів
  * @returns {string[]} лише css/scss/vue
@@ -12,6 +24,7 @@ export function filterStyleFiles(files) {
 }
 
 /**
+ * lint-поверхня: stylelint (per-file для css/scss/vue або весь проєкт у `--full`).
  * @param {string[] | undefined} files per-file: ці файли; undefined: весь проєкт (--full)
  * @param {string} [cwd] корінь
  * @param {{ readOnly?: boolean }} [opts] readOnly → без `--fix` (детект, нуль мутацій)
@@ -29,3 +42,8 @@ export function lint(files, cwd = process.cwd(), opts = {}) {
   const r = spawnSync('npx', args, { cwd, stdio: 'inherit' })
   return Promise.resolve(typeof r.status === 'number' ? r.status : 1)
 }
+
+if (isRunAsCli(import.meta.url)) {
+  // Standalone: bun rules/<id>/main.mjs — повний еквівалент `npx @nitra/cursor check <id>`.
+  process.exitCode = await runRuleCli(import.meta.dirname)
+}

package/rules/tauri/docs/index.md

@@ -9,3 +9,4 @@ resource: npm/rules/tauri/
 | Файл | Тип |
 |---|---|
 | [fix.mjs](fix.md) | JS Module |
+| [main.mjs](main.md) | JS Module |

package/rules/tauri/docs/main.md

@@ -0,0 +1,29 @@
+---
+type: JS Module
+title: main.mjs
+resource: npm/rules/tauri/main.mjs
+docgen:
+  crc: 762b6875
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+---
+
+## Огляд
+
+Модуль обробляє JS-запити та взаємодіє з MDC для отримання даних. При запуску через публічну функцію `run` він оркеструє застосування правил, завантажуючи конфігурації з meta.json, застосовуючи білий список та надаючи підсумок. Модуль є read-only і не здійснює записів у ФС/БД.
+
+## Поведінка
+
+1. Викликається функція `run` для виконання перевірки.
+2. Виконання перевірки включає застосування політики, обробку JS-запитань та посилання на MDC.
+3. Якщо код виконується як окрема утиліта (CLI), запускається оркестрація правила.
+4. Оркестрація правила виконує завантаження конфігурацій (наприклад, `meta.json`), застосовує білий список та надає підсумок.
+
+## Публічний API
+
+run — виконує основну логіку правила: застосовує вимоги до JavaScript, перевіряє політику та посилання на MDC.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).
+- Кешує результати в межах одного прогону.

package/rules/tauri/main.mjs

@@ -0,0 +1,20 @@
+import { isRunAsCli, runRuleCli } from '../../scripts/lib/run-rule-cli.mjs'
+import { runStandardRule } from '../../scripts/lib/run-standard-rule.mjs'
+
+/**
+ * Єдиний entrypoint правила (ADR 2026-06-21). `run()` — check-поверхня: applies →
+ * JS-concerns → policy → mdc-refs (через runStandardRule). Lint-поверхні правило не має
+ * (`meta.json` без `lint`), тож експорту `lint` тут немає.
+ * Library mode: викликається CLI orchestration через `import + run(ctx)`.
+ * @param {import('../../scripts/lib/run-standard-rule.mjs').RuleContext} [ctx] контекст прогону (walkCache тощо)
+ * @returns {Promise<number>} 0 — OK, 1 — порушення
+ */
+export function run(ctx) {
+  return runStandardRule(import.meta.dirname, ctx)
+}
+
+if (isRunAsCli(import.meta.url)) {
+  // Standalone: bun rules/<id>/main.mjs — повний еквівалент `npx @nitra/cursor check <id>`
+  // (config-loading + whitelist + summary): library-роль (run) + standalone-роль (CLI-блок).
+  process.exitCode = await runRuleCli(import.meta.dirname)
+}

package/rules/test/docs/index.md

@@ -9,3 +9,4 @@ resource: npm/rules/test/
 | Файл | Тип |
 |---|---|
 | [fix.mjs](fix.md) | JS Module |
+| [main.mjs](main.md) | JS Module |

package/rules/test/docs/main.md

@@ -0,0 +1,30 @@
+---
+type: JS Module
+title: main.mjs
+resource: npm/rules/test/main.mjs
+docgen:
+  crc: 762b6875
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+---
+
+## Огляд
+
+Модуль виконує перевірку, обробляючи JS-запитання, політику та посилання на mdc. При запуску як окрема програма, він зчитує конфігурації з meta.json, застосовує білий список та підсумовує результати після застосування білого списку, визначаючи код виходу процесу. Функція run ініціює цей процес. Модуль є read-only і не пише у ФС/БД. Кешування відбувається у межах прогону.
+
+## Поведінка
+
+1. Викликається функція `run` для виконання перевірки.
+2. Виконання `run` застосовує логіку правила, включаючи обробку JS-запитань, політику та посилання на mdc.
+3. Якщо скрипт виконується як окрема програма (CLI), запускається оркестрація правила.
+4. Оркестрація правила зчитує конфігурації, включаючи `meta.json`, застосовує білий список та підсумовує результати.
+5. Результат оркестрації визначає код виходу процесу.
+
+## Публічний API
+
+run — виконує основну логіку правила: застосовує перевірки, обробляє JS-залежності та політики, а також посилається на метадані.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).
+- Кешує результати в межах одного прогону.

package/rules/test/main.mjs

@@ -0,0 +1,20 @@
+import { isRunAsCli, runRuleCli } from '../../scripts/lib/run-rule-cli.mjs'
+import { runStandardRule } from '../../scripts/lib/run-standard-rule.mjs'
+
+/**
+ * Єдиний entrypoint правила (ADR 2026-06-21). `run()` — check-поверхня: applies →
+ * JS-concerns → policy → mdc-refs (через runStandardRule). Lint-поверхні правило не має
+ * (`meta.json` без `lint`), тож експорту `lint` тут немає.
+ * Library mode: викликається CLI orchestration через `import + run(ctx)`.
+ * @param {import('../../scripts/lib/run-standard-rule.mjs').RuleContext} [ctx] контекст прогону (walkCache тощо)
+ * @returns {Promise<number>} 0 — OK, 1 — порушення
+ */
+export function run(ctx) {
+  return runStandardRule(import.meta.dirname, ctx)
+}
+
+if (isRunAsCli(import.meta.url)) {
+  // Standalone: bun rules/<id>/main.mjs — повний еквівалент `npx @nitra/cursor check <id>`
+  // (config-loading + whitelist + summary): library-роль (run) + standalone-роль (CLI-блок).
+  process.exitCode = await runRuleCli(import.meta.dirname)
+}

package/rules/text/docs/index.md

@@ -9,3 +9,4 @@ resource: npm/rules/text/
 | Файл | Тип |
 |---|---|
 | [fix.mjs](fix.md) | JS Module |
+| [main.mjs](main.md) | JS Module |

package/rules/text/docs/main.md

@@ -0,0 +1,29 @@
+---
+type: JS Module
+title: main.mjs
+resource: npm/rules/text/main.mjs
+docgen:
+  crc: deba6201
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 90
+---
+
+## Огляд
+
+CLI-обгортка над канонічним `lint-text` (text.mdc) забезпечує послідовний пайплайн перевірок для текстових файлів. Вона автоматично встановлює необхідні інструменти (`shellcheck`, `dotenv-linter`) через `ensureTool` (brew/scoop/GitHub Release per-platform) та перевіряє наявність `patch` для авто-фіксу. Пайплайн послідовно виконує: перевірку правопису (`cspell` з `@nitra/cspell-dict`), синтаксичну перевірку скриптів (`shellcheck` з авто-фіксом), перевірку конфігураційних файлів (`dotenv-linter` з авто-фіксом), форматування Markdown (`markdownlint-cli2` з авто-фіксом) та валідацію схем (`v8r`). Перший ненульовий код, отриманий у ланцюжку, повертається як код виходу, припиняючи подальші кроки. Функціональність експортується як `runLintTextCli` та викликається через `n-cursor lint text` (оркестраторний адаптер `lint`). Конфігурації, на які спирається код: meta.json.
+
+## Поведінка
+
+run: Викликається як check-поверхня, виконуючи стандартне правило.
+runLintTextCli: Виконує повний ланцюжок перевірок для тексту: `cspell`, `shellcheck`, `dotenv-linter`, `markdownlint-cli2` та валідацію схем через `v8r`. Автоматично встановлює `shellcheck` та `dotenv-linter` при першому прогоні. Повертає код першого кроку, що не пройшов.
+lint: Делегує виконання повного ланцюжка перевірок тексту через `runLintTextCli`, дозволяючи вказати режим лише детектування без авто-фіксу.
+
+## Публічний API
+
+run — Точка входу правила, що виконує перевірку логіки (JS-занепокложення → політика → посилання text.mdc).
+runLintTextCli — Публічна команда для CLI, яка серіалізує завдання лінтування з блокуванням та усуває дублікати на основі стану репозиторію.
+lint — Адаптер, що керує запуском лінтування тексту через `n-cursor lint text`, делегуючи роботу `runLintTextCli`.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).

package/rules/text/js/docs/cspell-fix.md

@@ -0,0 +1,30 @@
+---
+type: JS Module
+title: cspell-fix.mjs
+resource: npm/rules/text/js/cspell-fix.mjs
+docgen:
+  crc: 7b40e8f9
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+---
+
+## Огляд
+
+Виявляє невідомі слова у тексті у ланцюжку lint-text із omlx-класифікацією (спека docs/specs/2026-06-15-opportunistic-llm-fix-tier.md), використовуючи конфігурації .cspell.json та meta.json. Класифікує знахідки за схемою omlx-класифікація, дописуючи валідні терміни до словника .cspell.json. Ймовірні одруки залишаються списком на рев'ю, оскільки fix-режим не переписує файли. Завершує процес повторною перевіркою, щоб визначити, чи залишилися нерозкласифіковані або ймовірні одруки. Перехоплює помилки (fail-safe), не кидаючи винятків назовні.
+
+## Поведінка
+
+unknownWords витягує унікальні невідомі слова з виводу cspell.
+appendWordsToDict додає класифіковані валідні слова до файлу .cspell.json, оновлюючи його словник.
+runCspellText запускає cspell для виявлення невідомих слів, а при увімкненні omlx-класифікації класифікує їх та дописує валідні слова у словник, після чого повторно перевіряє наявність помилок.
+
+## Публічний API
+
+unknownWords — Збирає унікальні слова, які не були знайдені у словнику cspell.
+appendWordsToDict — Додає зібрані слова до файлу `.cspell.json#words` у відсортованому та унікальному вигляді для перегляду у Git.
+runCspellText — Виконує перевірку тексту за допомогою cspell, класифікуючи слова та оновлюючи словник за новою схемою.
+
+## Гарантії поведінки
+
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).
+- За певних помилок повертає порожнє значення (напр. `null`) замість винятку.

package/rules/text/js/docs/formatting.md

@@ -3,61 +3,28 @@ type: JS Module
 title: formatting.mjs
 resource: npm/rules/text/js/formatting.mjs
 docgen:
-  crc: 67b016e2
+  crc: 34048813
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 100
 ---
 
-Перевіряє наявність файлів з конфігурацій. Код використовує дані з конфігів з extensions.json, settings.json, target.json, .oxfmtrc.json, .cspell.json та package.json для виконання операцій.
+Модуль перевіряє відповідність конфігураційних файлів та скриптів встановленим вимогам. Він перевіряє наявність конфігураційних файлів, на які спираються `package.json`, `extensions.json`, `target.json`, `.oxfmtrc.json` та `.cspell.json`. Модуль використовує функцію `check` для валідації налаштувань.
 
 ## Поведінка
 
-1. Перевірити наявність файлів з конфігурацій
-2. Перевірити наявність файлів з конфігурацій
-3. Перевірити наявність файлів з конфігурацій
-4. Перевірити наявність файлів з конфігурацій
-5. Перевірити наявність файлів з конфігурацій
-6. Перевірити наявність файлів з конфігурацій
-7. Перевірити наявність файлів з конфігурацій
-8. Перевірити наявність файлів з конфігурацій
-9. Перевірити наявність файлів з конфігурацій
-10. Перевірити наявність файлів з конфігурацій
-11. Перевірити наявність файлів з конфігурацій
-12. Перевірити наявність файлів з конфігурацій
-13. Перевірити наявність файлів з конфігурацій
-14. Перевірити наявність файлів з конфігурацій
-15. Перевірити наявність файлів з конфігурацій
-16. Перевірити наявність файлів з конфігурацій
-17. Перевірити наявність файлів з конфігурацій
-18. Перевірити наявність файлів з конфігурацій
-19. Перевірити наявність файлів з конфігурацій
-20. Перевірити наявність файлів з конфігурації
-21. Перевірити наявність файлів з конфігурації
-22. Перевірити наявність файлів з конфігурації
-23. Перевірити наявність файлів з конфігурації
-24. Перевірити наявність файлів з конфігурації
-25. Перевірити наявність файлів з конфігурації
-26. Перевірити наявність файлів з конфігурації
-27. Перевірити наявність файлів з конфігурації
-28. Перевірити наявність файлів з конфігурації
-29. Перевірити наявність файлів з конфігурації
-30. Перевірити наявність файлів з конфігурації
-31. Перевірити наявність файлів з конфігурації
-32. Перевірити наявність файлів з конфігурації
-33. Перевірити наявність файлів з конфігурації
-34. Перевірити наявність файлів з конфігурації
-35. Перевірити наявність файлів з конфігурації
-36. Перевірити наявність файлів з конфігурації
-37. Перевірити наявність файлів з конфігурації
-38. Перевірити наявність файлів з конфігурації
-39. Перевірити наявність файлів з конфігурації
-40. Перевірити наявність файлів з конфігурації
+1. Викликається функція check.
+2. Ініціалізується механізм збору результатів перевірки.
+3. Виконується перевірка файлу .v8rignore на відповідність вимогам.
+4. Виконується перевірка наявності текстових конфігураційних файлів: .oxfmtrc.json, .cspell.json, .markdownlint-cli2.jsonc, .vscode/extensions.json, .vscode/settings.json.
+5. Перевіряється абзац про український апостроф у файлах n-text.mdc або npm/mdc/text.mdc, якщо вони існують.
+6. Виконується перевірка CI-workflow у файлі .github/workflows/lint-text.yml на наявність кроку `n-cursor lint text --read-only`.
+7. Повертається код виходу, що відображає загальний статус перевірки.
 
 ## Публічний API
 
-check — перевіряє відповідність проєкту правилам text.mdc (text.mdc).
+check — порівнює структуру проєкту з вимогами text.mdc.
 
 ## Гарантії поведінки
 
-- Read-only: файл не виконує операцій запису у файлову систему.
+- Read-only: не виконує операцій запису (ФС/БД).
 - Свідомо пропускає шляхи: `.github`, `.git`.
-- Не звертається до мережі.

package/rules/text/js/docs/index.md

@@ -8,6 +8,10 @@ resource: npm/rules/text/js/
 
 | Файл | Тип |
 |---|---|
+| [cspell-fix.mjs](cspell-fix.md) | JS Module |
 | [forbidden-prettier.mjs](forbidden-prettier.md) | JS Module |
 | [formatting.mjs](formatting.md) | JS Module |
 | [lint.mjs](lint.md) | JS Module |
+| [run-dotenv-linter.mjs](run-dotenv-linter.md) | JS Module |
+| [run-shellcheck.mjs](run-shellcheck.md) | JS Module |
+| [run-v8r.mjs](run-v8r.md) | JS Module |

package/rules/text/js/docs/run-dotenv-linter.md

@@ -0,0 +1,31 @@
+---
+type: JS Module
+title: run-dotenv-linter.mjs
+resource: npm/rules/text/js/run-dotenv-linter.mjs
+docgen:
+  crc: 4719ac66
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+---
+
+## Огляд
+
+Модуль запускає `dotenv-linter` для валідації конфігураційних файлів `.env*` відповідно до стандартів (наприклад, `LowercaseKey`). Процес включає два етапи: спочатку автоматичне виправлення порушень за допомогою `dotenv-linter fix`, а потім фінальну перевірку за допомогою `dotenv-linter check`. Інструмент очікується у системному PATH і не включається у залежності проєкту. Він рекурсивно шукає файли, виключаючи `node_modules` та `.envrc`. Якщо `dotenv-linter` відсутній, виводиться інструкція щодо його встановлення (наприклад, `brew install dotenv-linter`) та повертається код помилки. Усі деталі роботи можна знайти за посиланням https://git.io/JLbXn.
+
+## Поведінка
+
+1. `runDotenvLinter` перевіряє наявність інструменту `dotenv-linter` у системному шляху. Якщо інструмент відсутній, виводиться підказка для його встановлення (наприклад, `brew install dotenv-linter` для macOS або завантаження за адресою https://git.io/JLbXn для Linux) та повертається код виходу 1.
+2. Якщо інструмент знайдено, будується список виключених шляхів для сканування, включаючи `node_modules` та `.envrc`.
+3. Якщо режим роботи не є лише перевіркою (readOnly дорівнює `false`), виконується перший запуск `dotenv-linter` з опцією авто-фіксу. Цей запуск застосовує всі можливі виправлення до `.env*`-файлів, ігноруючи `.bak`-файли.
+4. Після застосування авто-фіксу, виконується фінальний запуск `dotenv-linter` з опцією перевірки.
+5. Якщо фінальна перевірка повертає ненульовий код виходу, це означає, що залишилися порушення, і повертається код виходу 1.
+6. Якщо фінальна перевірка повертає код виходу 0, операція успішна, і повертається код виходу 0.
+
+## Публічний API
+
+runDotenvLinter — запускає dotenv-linter з автоматичним виправленням та фінальною перевіркою конфігураційних файлів.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).
+- Свідомо пропускає шляхи: `node_modules`.

package/rules/text/js/docs/run-shellcheck.md

@@ -0,0 +1,28 @@
+---
+type: JS Module
+title: run-shellcheck.mjs
+resource: npm/rules/text/js/run-shellcheck.mjs
+docgen:
+  crc: 6b2daaa8
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+---
+
+## Огляд
+
+Скрипт забезпечує відповідність shell-скриптів стандартам, виконуючи дві послідовні дії: спочатку застосовує автоматичні виправлення для проблем, виявлених `shellcheck` за допомогою формату виводу `diff` та команди `patch -p1` у корені проєкту; потім проводить фінальну перевірку всіх зібраних файлів. Скрипт збирає всі відстежувані shell-скрипти у робочому дереві, ігноруючи директорії `node_modules`. Якщо скриптів не знайдено, процес завершується з кодом 0. Якщо `shellcheck` або `patch` відсутні у PATH, скрипт завершується з кодом 1, надаючи підказки для їх встановлення. Після циклу автовиправлень будь-яке попередження чи помилка від `shellcheck` призводить до ненульового коду виходу.
+
+## Поведінка
+
+listShellScriptPaths повертає відсортований масив відносних шляхів до shell-скриптів у проєкті, виключаючи директорії `node_modules`.
+runShellcheckText запускає shellcheck: спочатку намагається автоматично виправити знайдені проблеми за допомогою `diff` та `patch`, а потім виконує фінальну перевірку всіх зібраних файлів.
+
+## Публічний API
+
+listShellScriptPaths — надає список шляхів до скриптів оболонки для перевірки.
+runShellcheckText — виконує перевірку коду за допомогою shellcheck з автоматичним виправленням.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).
+- Свідомо пропускає шляхи: `node_modules`.

package/rules/text/js/docs/run-v8r.md

@@ -0,0 +1,29 @@
+---
+type: JS Module
+title: run-v8r.mjs
+resource: npm/rules/text/js/run-v8r.mjs
+docgen:
+  crc: caf707a8
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+---
+
+## Огляд
+
+Скрипт виконує єдиний виклик `v8r` для перевірки відповідності всіх файлів, які підтримує `v8r` (json, json5, yaml, yml, toml), визначеним контрактам. Це замінює необхідність у кількох окремих викликах `v8r`. Скрипт автоматично використовує каталог схем `@nitra/cursor`, який визначається у `v8r-catalog.json`. Якщо не надано додаткових аргументів, він шукає файли за типовими шаблонами у дереві проєкту. Механізм гарантує, що перевірка всіх розширень відбувається, навіть якщо один із глобів не знаходить файлів, оскільки він обходить проблему падіння `v8r` з кодом 98.
+
+## Поведінка
+
+DEFAULT_V8R_GLOBS — надає стандартний список патернів для пошуку файлів JSON, JSON5, YAML, YML та TOML.
+V8R_CATALOG_PATH — визначає абсолютний шлях до каталогу схем `v8r-catalog.json` у корені пакета `@nitra/cursor`.
+runV8rWithGlobs — послідовно запускає перевірку кожного наданого патерну за допомогою `v8r`, використовуючи `v8r-catalog.json` як конфігурацію схем. Повертає код завершення, відображаючи вивід лише при виявленні помилки.
+
+## Публічний API
+
+* DEFAULT_V8R_GLOBS — Містить стандартні шаблони для пошуку файлів, які обробляє v8r.
+* V8R_CATALOG_PATH — Вказує на розташування файлу `v8r-catalog.json` у корені пакета.
+* runV8rWithGlobs — Виконує послідовні запуски v8r для файлів, знайдених за шаблонами, повертаючи код завершення.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).