@7n/rules 1.7.0 → 1.7.1

package/rules/tauri/tool_surface/tool_surface.mdc

@@ -0,0 +1,29 @@
+## Tool Surface у Tauri (реалізація ядра `tool-surface`)
+
+Це per-stack реалізація правила **`tool-surface`** (`n-tool-surface`) для Tauri+Rust. Контракт (каталог → `dispatch` → UI/оркестратор/LLM, інваріант паритету, конверт) — у тому правилі; тут — як він лягає на Tauri.
+
+**Реальна робота живе в Rust, JS-каталог — тонкий call surface.** Handler тула не містить логіки сам — він **делегує** в native. Одна реалізація в Rust-крейті backs два споживачі:
+
+- **Бінарник** (`src-tauri` як CLI, або окремий crate-bin) — headless-вхід для оркестратора;
+- **Tauri-команда** (`#[tauri::command]`) — той самий крейт-fn, обгорнутий для UI.
+
+**Два транспорти одного каталогу** (`src/tool/transports`):
+
+- **UI (in-app):** `invoke(tool.tauri, input)` → Tauri-команда → крейт. Ключі `input` мапляться 1:1 на аргументи команди (camelCase, напр. `tasksDir`); поля вкладених struct лишаються snake_case (Tauri конвертить лише імена top-level аргументів).
+- **Оркестратор (headless):** `bin/<app>.mjs` спавнить зібраний бінарник (`<bin> <verb> …` per-verb, або уніфікований `<bin> exec '<json>'`), парсить JSON stdout.
+
+**Конверт:** Tauri-команда повертає `Result<T, String>`; адаптер мапить у `{ ok, output }` / `{ ok:false, error }`. Бінарник друкує конверт у stdout, exit ≠ 0 на `ok:false`.
+
+**Єдине джерело схем:** надавай перевагу `schemars`-derive на Rust-param-структурах → бінарник віддає маніфест (`<bin> schema`); або тримай схему в JS-каталозі й валідуй до `invoke`. **Не дублюй** контракт між Rust і JS — лише деривація + спільні тест-вектори.
+
+**LLM-раннер in-app:** chat-loop ходить до OpenAI-сумісного ендпоінта через `tauri-plugin-http` fetch (бо webview-fetch обмежений CSP/capability), а тули виконує через спільний `dispatch` (той самий, що й UI).
+
+### Що перевіряє автоматичний lint (`main.mjs`)
+
+Для кожного Tauri-workspace (маркер — `tauri.conf.json` чи `src-tauri/tauri.conf.json`) детектор збирає slugs плагінів, яких торкається JS/TS/Vue-код у `src/**`: через wrapper-import `@tauri-apps/plugin-<slug>` або прямий `invoke('plugin:<slug>|<command>')`. Для кожного знайденого `<slug>` перевіряються три незалежні умови — будь-яка провалена дає окрему violation:
+
+1. **`tool-surface-plugin-dep-missing`** — `src-tauri/Cargo.toml` не оголошує crate `tauri-plugin-<slug>` у жодній секції `[dependencies]`/`[target.*.dependencies]`.
+2. **`tool-surface-plugin-not-registered`** — `src-tauri/src/lib.rs` ніде не згадує rust-ідентифікатор плагіна (`tauri-plugin-dialog` → `tauri_plugin_dialog`, дефіси заміняються на підкреслення), тобто `builder` його не реєструє.
+3. **`tool-surface-plugin-capability-missing`** — жоден файл `src-tauri/capabilities/*.json` не дає permission `<slug>` чи `<slug>:*`.
+
+Кожна з трьох дір — тихий рантайм-фейл без компіляційної помилки: (1) код не збереться на CI іншого профілю або впаде при оновленні залежностей, (2) `invoke` впаде з "plugin not found", (3) `invoke` впаде permission-denied, видимий лише в `console.error`. Перевірено вживу на проєкті myllm.

package/rules/test/vitest-api-conventions/concern.json

@@ -0,0 +1,7 @@
+{
+  "$schema": "https://unpkg.com/@7n/rules/schemas/concern.json",
+  "lint": {
+    "scope": "full",
+    "glob": ["**/*.test.mjs", "**/*.test.js"]
+  }
+}

package/rules/test/vitest-api-conventions/docs/index.md

@@ -0,0 +1,9 @@
+---
+type: Directory Index
+title: npm/rules/test/vitest-api-conventions
+resource: npm/rules/test/vitest-api-conventions/
+---
+
+| Файл                 | Тип       |
+| -------------------- | --------- |
+| [main.mjs](main.md)  | JS Module |

package/rules/test/vitest-api-conventions/docs/main.md

@@ -0,0 +1,40 @@
+---
+type: JS Module
+title: main.mjs
+resource: npm/rules/test/vitest-api-conventions/main.mjs
+docgen:
+  crc: 4ef8e575
+---
+
+## Огляд
+
+Детектор concern-а `vitest-api-conventions`: перевіряє, що жоден тестовий файл проєкту
+не викликає `expect(...).toBe(...)` з об'єктним чи масивним літералом як першим аргументом.
+Така перевірка завжди хибна незалежно від вмісту (reference equality на новоствореному
+значенні) — канонічна заміна для об'єктів/масивів — `toEqual` (deep equality).
+
+## Поведінка
+
+Обходить дерево проєкту (пропускаючи `node_modules` і шляхи з cursor-ignore) і збирає всі
+файли з іменем `*.test.mjs`/`*.test.js`. У кожному файлі шукає виклики `.toBe(`, чий перший
+аргумент — саме об'єктний (`{...}`) чи масивний (`[...]`) літерал: сканує парність дужок
+з урахуванням рядкових і template-літералів усередині, щоб не збитись на дужки в рядках.
+Виклик рахується порушенням лише якщо одразу після закриваючої дужки літерала (з пропуском
+пробілів) іде дужка, що закриває сам виклик, `)` — тобто ланцюжок на кшталт
+`.toBe([...].join('\n'))` не матчиться, бо результат виклику — рядок-примітив, а не
+посилання на масив/обʼєкт.
+
+Для кожного знайденого випадку формує порушення з файлом (відносний шлях від cwd) і
+номером рядка.
+
+## Публічний API
+
+`lint(ctx)` — читає всі тестові файли проєкту (`ctx.cwd`), перевіряє їх на заборонений
+патерн `toBe` з об'єктним/масивним літералом і повертає список порушень
+(`{ file, message, reason }` на кожен знайдений виклик), або порожній результат, якщо
+жоден тестовий файл не порушує конвенцію (test.mdc, vitest-api-conventions).
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД) — лише читає файли й повертає порушення.
+- Сканує лише `*.test.mjs`/`*.test.js`; інші файли (в т.ч. `node_modules`) ігноруються.

package/rules/test/vitest-api-conventions/main.mjs

@@ -0,0 +1,186 @@
+/** @see ./docs/main.md */
+import { readFile } from 'node:fs/promises'
+import { basename, relative } from 'node:path'
+
+import { createViolationReporter } from '../../../scripts/lib/lint-surface/violation-reporter.mjs'
+import { loadCursorIgnorePaths } from '../../../scripts/lib/load-cursor-config.mjs'
+import { walkDir } from '../../../scripts/utils/walkDir.mjs'
+
+/**
+ * `expect(x).toBe({…})` / `expect(x).toBe([…])` — `toBe` — це `Object.is`
+ * (reference equality); нове об'єктне/масивне літеральне значення завжди має інше
+ * посилання, тож перевірка **завжди false**, незалежно від вмісту. Канон — `toEqual`
+ * (deep equality) для об'єктів і масивів (vitest-api-conventions.mdc, п.4).
+ * Знаходить лише `.toBe(` де аргумент — САМЕ літерал (нічого не приєднано після
+ * закриваючої дужки, окрім опційних пробілів і `)`) — `.toBe([...].join('\n'))`
+ * не матчиться: результат `.join()` — рядок-примітив, а не масив-посилання.
+ */
+const TO_BE_CALL_RE = /\.toBe\(/gu
+/** Whitespace-символ (пробіл/таб/перенос) — для `skipWhitespace`, module scope (oxlint prefer-static-regex). */
+const WS_RE = /\s/u
+/** Рядкові/template-лапки, що відкривають літерал усередині `findMatchingBracketEnd`. */
+const QUOTE_CHARS = new Set(['"', "'", '`'])
+/** Мапа закриваючої дужки на парну дужку, яка її відкриває — для перевірки балансу стеку. */
+const CLOSE_TO_OPEN = { '}': '{', ']': '[' }
+
+/**
+ * Чи файл — JS-тест (`*.test.mjs` / `*.test.js`).
+ * @param {string} absPath абсолютний шлях
+ * @returns {boolean} `true` для `.test.{mjs,js}` файлів
+ */
+function isTestFile(absPath) {
+  const name = basename(absPath)
+  return name.endsWith('.test.mjs') || name.endsWith('.test.js')
+}
+
+/**
+ * Пропускає пробіли/переноси рядків, повертає індекс першого не-whitespace символу.
+ * @param {string} body вміст файлу
+ * @param {number} from стартовий індекс
+ * @returns {number} індекс першого значущого символу (може дорівнювати `body.length`)
+ */
+function skipWhitespace(body, from) {
+  let i = from
+  while (i < body.length && WS_RE.test(body[i])) i++
+  return i
+}
+
+/**
+ * Просуває сканер на один крок усередині рядкового/template-літералу: обробляє
+ * екранування (`\x`) і повідомляє, чи саме на цьому символі рядок закрився.
+ * Виокремлено з `findMatchingBracketEnd`, аби тримати cognitive complexity
+ * головного циклу під порогом лінтера.
+ * @param {string} body вміст файлу
+ * @param {number} i індекс поточного символу (усередині рядка)
+ * @param {string} quote символ лапки, що відкриває поточний рядок
+ * @returns {{next: number, closed: boolean}} нова позиція сканера і прапорець закриття
+ */
+function stepInsideQuote(body, i, quote) {
+  const ch = body[i]
+  if (ch === '\\') return { next: i + 2, closed: false }
+  if (ch === quote) return { next: i + 1, closed: true }
+  return { next: i + 1, closed: false }
+}
+
+/**
+ * Знаходить індекс символу, що йде одразу за парною дужкою, яка закриває
+ * дужку на позиції `openIndex` (`{` чи `[`). Ігнорує дужки всередині
+ * рядкових/template-літералів, аби не збитись на `{ a: '}' }` тощо.
+ * @param {string} body вміст файлу
+ * @param {number} openIndex індекс відкриваючої дужки
+ * @returns {number|null} індекс одразу після закриваючої дужки, або `null` якщо не збалансовано
+ */
+function findMatchingBracketEnd(body, openIndex) {
+  const stack = [body[openIndex]]
+  let i = openIndex + 1
+  let quote = null
+
+  while (i < body.length) {
+    if (quote) {
+      const step = stepInsideQuote(body, i, quote)
+      if (step.closed) quote = null
+      i = step.next
+      continue
+    }
+
+    const ch = body[i]
+
+    if (QUOTE_CHARS.has(ch)) {
+      quote = ch
+      i++
+      continue
+    }
+
+    if (ch === '{' || ch === '[') {
+      stack.push(ch)
+      i++
+      continue
+    }
+
+    if (ch in CLOSE_TO_OPEN) {
+      if (stack.at(-1) !== CLOSE_TO_OPEN[ch]) return null // незбалансовано — здаємось
+      stack.pop()
+      if (stack.length === 0) return i + 1
+      i++
+      continue
+    }
+
+    i++
+  }
+
+  return null
+}
+
+/**
+ * Знаходить усі виклики `.toBe(` де перший аргумент — САМЕ об'єктний/масивний
+ * літерал (не результат ланцюжка викликів на ньому).
+ * @param {string} body вміст файлу
+ * @returns {Array<{line: number}>} знайдені порушення
+ */
+function findOffenders(body) {
+  const offenders = []
+  for (const m of body.matchAll(TO_BE_CALL_RE)) {
+    const argStart = skipWhitespace(body, m.index + m[0].length)
+    const ch = body[argStart]
+    if (ch !== '{' && ch !== '[') continue
+
+    const afterLiteral = findMatchingBracketEnd(body, argStart)
+    if (afterLiteral === null) continue
+
+    const afterWs = skipWhitespace(body, afterLiteral)
+    if (body[afterWs] !== ')') continue // приєднано щось після літерала (напр. .join(...)) — не порушення
+
+    const line = body.slice(0, m.index).split('\n').length
+    offenders.push({ line })
+  }
+  return offenders
+}
+
+/**
+ * Detector: жоден `*.test.{mjs,js}` не викликає `expect(...).toBe(...)` з
+ * об'єктним/масивним літералом — `toBe` (Object.is) на новоствореному
+ * об'єкті/масиві завжди false; канон — `toEqual` (vitest-api-conventions.mdc, п.4).
+ * @param {import('../../../scripts/lib/lint-surface/types.mjs').LintContext} ctx контекст лінту.
+ * @returns {Promise<import('../../../scripts/lib/lint-surface/types.mjs').LintResult>} результат перевірки з порушеннями.
+ */
+export async function lint(ctx) {
+  const reporter = createViolationReporter(ctx)
+  const { pass, fail } = reporter
+
+  const cwd = ctx.cwd
+  const ignorePaths = await loadCursorIgnorePaths(cwd)
+
+  /** @type {string[]} */
+  const testFiles = []
+  await walkDir(
+    cwd,
+    absPath => {
+      if (isTestFile(absPath)) testFiles.push(absPath)
+    },
+    ignorePaths
+  )
+
+  /** @type {Array<{file: string, line: number}>} */
+  const offenders = []
+  for (const absPath of testFiles) {
+    const body = await readFile(absPath, 'utf8')
+    for (const o of findOffenders(body)) {
+      offenders.push({ file: relative(cwd, absPath), ...o })
+    }
+  }
+
+  if (offenders.length === 0) {
+    pass(`Жоден з ${testFiles.length} тестових файлів не викликає toBe(...) з об'єктним/масивним літералом (test.mdc)`)
+    return reporter.result()
+  }
+
+  for (const { file, line } of offenders) {
+    fail(
+      `${file}:${line}: expect(...).toBe(...) з об'єктним/масивним літералом завжди false ` +
+        `(Object.is на новому посиланні) — використовуй toEqual (test.mdc, vitest-api-conventions)`,
+      { file }
+    )
+  }
+
+  return reporter.result()
+}

package/rules/test/vitest-api-conventions/vitest-api-conventions.mdc

@@ -0,0 +1,129 @@
+## Vitest API — обов'язкові конвенції (для генерації тестів LLM)
+
+Цей розділ адресований генераторам тестів (LLM, local і cloud). Порушення будь-якого пункту — рівнозначне синтаксичній помилці: тест не запуститься або дасть хибно-позитивний результат.
+
+Канон: тести виконуються через **vitest** під Bun-рушієм (`bun run --bun vitest run`, див. `test.package_json`), а не через нативний `bun test` — `import ... from 'bun:test'` заборонено (`no-bun-test-import`). API нижче — саме vitest, не bun:test і не jest.
+
+### 1. Модульна система — лише ESM
+
+`*.test.mjs` завжди ESM; `require()` у `.mjs` кидає `ERR_REQUIRE_ESM`.
+
+✓ `import { foo } from '../foo.mjs'`
+✗ `const { foo } = require('../foo.mjs')`
+
+### 2. `vi.*` замість `jest.*`
+
+Проект використовує Vitest, не Jest. Будь-який `jest.fn()`, `jest.mock()`, `jest.spyOn()` — помилка компіляції або runtime-помилка.
+
+✓ `vi.fn()`, `vi.mock(...)`, `vi.spyOn(...)`
+✗ `jest.fn()`, `jest.mock(...)`, `jest.spyOn(...)`
+
+### 3. Кастинг mock-функцій — лише `vi.mocked()`
+
+✓ `vi.mocked(fetch).mockResolvedValue(res)`
+✗ `(fetch as vi.Mock).mockResolvedValue(res)` — TypeScript у `.mjs` не компілюється
+
+### 4. `toBe` vs `toEqual`
+
+`toBe` (Object.is) — для примітивів (`string`, `number`, `boolean`, `null`, `undefined`).
+`toEqual` (deep equality) — для об'єктів і масивів.
+
+`toBe({…})` для об'єктів **завжди false** (різні посилання) — використовуй `toEqual`.
+
+✓ `expect(count).toBe(3)`
+✓ `expect(result).toEqual({ ok: true })`
+✗ `expect(result).toBe({ ok: true })`
+
+**Перевірка** (`rules/test/vitest-api-conventions/main.mjs`): сканує `**/*.test.{mjs,js}`, шукає `expect(...).toBe(...)` з об'єктним/масивним літералом як першим аргументом — таке порівняння завжди `false` через reference equality, незалежно від вмісту.
+
+### 5. Моки для Date / часу
+
+`vi.spyOn(Date).mockReturnValue(…)` **не працює** з `new Date()` (TypeError: Date is not a constructor при `new`).
+
+✓
+
+```js
+vi.useFakeTimers()
+vi.setSystemTime(new Date('2024-01-01'))
+afterEach(() => vi.useRealTimers())
+```
+
+✗ `vi.spyOn(global, 'Date').mockReturnValue(new Date('2024-01-01'))`
+
+### 6. Моки для `process.env`
+
+`process.env.X = '…'` забруднює глобальний стан; `vi.spyOn(process, 'env')` не дає ізоляції між тестами.
+
+✓
+
+```js
+vi.stubEnv('KEY', 'val')
+afterEach(() => vi.unstubAllEnvs())
+```
+
+✗ `process.env.KEY = 'val'` (без відновлення)
+
+### 7. Модулі з top-level side-effect
+
+Якщо source-модуль читає `process.env` або викликає функцію на рівні модуля — env/моки мають бути встановлені **до** `import`; сам import — dynamic.
+
+✓
+
+```js
+vi.stubEnv('KEY', 'val')
+const { fn } = await import('../index.js')
+```
+
+✗ статичний `import { fn } from '../index.js'` коли source викликає функцію на рівні модуля
+
+### 8. Cleanup у `afterEach` — обов'язковий
+
+Після кожного тест-файлу з mock-ами — відновлення стану:
+
+```js
+afterEach(() => {
+  vi.restoreAllMocks()
+  vi.unstubAllEnvs()
+  vi.useRealTimers() // лише якщо vi.useFakeTimers() використовувався
+})
+```
+
+Пропуск `afterEach` — витік стану між тестами в одному файлі.
+
+### 9. FormData у Node.js
+
+`formData.get('field')` повертає `Blob | string | null`. Для file-полів — `toBeInstanceOf(Blob)`, НЕ `toBe('filename')`.
+
+✓ `expect(formData.get('file')).toBeInstanceOf(Blob)`
+✗ `expect(formData.get('file')).toBe('photo.jpg')`
+
+---
+
+### Канонічний шаблон тест-файлу
+
+```js
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+import { myFn } from '../my-module.mjs'
+
+vi.mock('../dep.mjs', () => ({ dep: vi.fn() }))
+
+beforeEach(() => {
+  vi.stubEnv('API_KEY', 'test-key')
+  vi.useFakeTimers()
+  vi.setSystemTime(new Date('2024-06-01'))
+})
+
+afterEach(() => {
+  vi.restoreAllMocks()
+  vi.unstubAllEnvs()
+  vi.useRealTimers()
+})
+
+describe('myFn', () => {
+  it('повертає очікуване значення', async () => {
+    const result = await myFn()
+    expect(result).toEqual({ ok: true })
+  })
+})
+```

package/rules/text/cspell/cspell.mdc

@@ -39,3 +39,21 @@ Rego-пакет: `text.cspell`
 ```
 
 (відсутнє `language`, застарілий `version`, заборонений `@cspell/dict-`, не всі canonical `ignorePaths`)
+
+## Локальні виключення та мови
+
+Коли **cspell** підсвічує слово, спочатку **виправ текст**, а не розширюй словник:
+
+- виправ **друкарські помилки** та неправильні форми;
+- **перефразуй коректною українською** (або англійською, залежно від контексту файлу): заміни кальки й випадкові склади на звичні формулювання зі словників;
+- заміни **жаргон**, якщо є природний еквівалент у тому ж стилі документації (наприклад, у коментарях пиши «функція зворотного виклику» замість розмовного запозичення з англійського `callback`).
+
+У секцію `words` у `.cspell.json` додавай записи **лише якщо переписати коректно неможливо** або **недоречно**: власні назви, стабільні технічні терміни без усталеного перекладу в проєкті, ідентифікатори зовнішніх API тощо.
+
+### Інші мови
+
+**`@nitra/cspell-dict`** від `2.0.0` уже містить залежності на типові словники (`@cspell/dict-uk-ua`, `@cspell/dict-ru_ru` та інші) — якщо потрібна мова вже є серед них, додай лише код у поле `language` (наприклад `"en,uk,ru-ru,nitra"`), без окремих `@cspell/dict-*` у споживачі. Порядок у `import` може впливати на пріоритет словників — тримай корпоративний `@nitra/cspell-dict` першим, якщо додаєш інші розширення (рідко). Якщо мови немає в корпоративному пакеті — розширюй `@nitra/cspell-dict`, а не підключай `@cspell/dict-*` у корені репозиторію-споживача. Огляд upstream-словників: [streetsidesoftware/cspell-dicts](https://github.com/streetsidesoftware/cspell-dicts).
+
+### Fix-режим: класифікація через omlx
+
+cspell не має нативного `--fix`. Fix-режим **класифікує** знахідки через локальну LLM: detect → omlx-класифікація distinct-слів (bounded JSON-вихід) → валідні слова авто-дописуються у `.cspell.json#words` (sorted/dedup) → ймовірні одруки лишаються списком на ревʼю (не авто-виправляються). Максимум 80 distinct-слів за прогін.

package/rules/text/markdownlint/markdownlint.mdc

@@ -38,3 +38,7 @@ Rego-пакет: `text.markdownlint`
   }
 }
 ```
+
+## MD041 вимкнено навмисно
+
+**MD041** (перший рядок файлу має бути top-level heading) вимкнено в каноні `.markdownlint-cli2.jsonc` навмисно: `.mdc`-файли починаються з YAML-frontmatter (`---`), не з `#`-заголовка, і MD041 хибно позначав би це порушенням. Деталі правил — [markdownlint-cli2](https://github.com/DavidAnson/markdownlint-cli2).

package/rules/text/run-dotenv-linter/run-dotenv-linter.mdc

@@ -0,0 +1,17 @@
+## dotenv-linter: перевірка `.env`-файлів
+
+**dotenv-linter** — швидкий лінтер для `.env`-файлів (перевіряє: LowercaseKey, DuplicatedKey, IncorrectDelimiter, UnorderedKey тощо). Інструмент має бути в **`PATH`** і **не** додається в `dependencies` / `devDependencies`.
+
+Якщо `dotenv-linter` відсутній — встанови локально:
+
+- **macOS:** `brew install dotenv-linter`
+- **Linux:** `curl -sSfL https://git.io/JLbXn | sh -s -- -b /usr/local/bin`
+- **cargo:** `cargo install dotenv-linter`
+
+**Запуск:** авто-фікс — один прогін `dotenv-linter fix --no-backup --quiet` (інструмент сам застосовує всі виправлення, без потреби у diff/patch, на відміну від shellcheck), потім фінальний `dotenv-linter check --quiet`; будь-яке залишкове порушення — ненульовий код виходу.
+
+Виключення (у full-режимі, рекурсивний `-r .`): `node_modules` і `.envrc` (direnv shell-синтаксис, не key=value формат). `.bak`-файли інструмент ігнорує самостійно. Якщо `.env*`-файлів немає, dotenv-linter повертає 0 («Nothing to check»).
+
+**Застереження:** `.env`-файли зазвичай git-ignored, а delta-список — це змінені tracked-файли, тож ignored `.env` у задачний прогін не потрапляють; реальна перевірка `.env*` живе у full/CI прогонах. Tracked файли на кшталт `.env.example` delta таки ловить.
+
+У CI — `--no-fix` (нуль мутацій): авто-фікс пропускається, лише `check`.

package/rules/text/run-shellcheck/run-shellcheck.mdc

@@ -0,0 +1,17 @@
+## shellcheck: перевірка shell-скриптів
+
+**shellcheck** — інструмент лише в **`PATH`**, **не** додавай до `dependencies` / `devDependencies`. VSCode-розширення — канон у `vscode_extensions` (`timonwong.shellcheck`).
+
+Якщо `shellcheck` відсутній — встанови локально:
+
+- **macOS:** `brew install shellcheck`
+- **Debian/Ubuntu:** `sudo apt-get install -y shellcheck`
+- **Arch:** `sudo pacman -S shellcheck`
+
+Потрібен також **`patch`** у `PATH` для авто-фіксу (на macOS зазвичай уже є; на Linux: `sudo apt-get install -y patch`). У read-only режимі (детект, CI) відсутність `patch` не блокує перевірку — лише авто-фікс.
+
+ShellCheck не має прапорця `--fix`. Авто-виправлення — цикл `shellcheck -f diff` + `patch -p1` (до 32 ітерацій на файл, захист від зациклення), потім звичайний повний прогін `shellcheck` по всіх зібраних файлах для фінальної перевірки.
+
+Список файлів: у git-робочому дереві — `git ls-files` з pathspec `:(glob)**/*.sh`; інакше — `globSync` з виключенням `node_modules`. Якщо скриптів не знайдено — вихід 0.
+
+Delta-лінт (`npx @7n/rules lint`) перевіряє лише змінені `*.sh`-файли; повний прогін (`--full`) — усі tracked `*.sh` у репо.

package/rules/text/run-v8r/run-v8r.mdc

@@ -0,0 +1,23 @@
+## v8r: валідація JSON/YAML/TOML за Schema Store
+
+**`v8r`** — інструмент валідації файлів за схемами з [Schema Store](https://www.schemastore.org/). Використовуй лише через **`bunx v8r`**, не в `devDependencies`.
+
+Canonical запуск — через lint-адаптер `n-rules lint text`: під капотом окремий каталог схем `npm/schemas/v8r-catalog.json` пакета `@7n/rules` (локальні схеми у `npm/schemas/` і `npm/schemas/vendor/`, self-contained, без мережевих `$ref`) підставляється в v8r як `customCatalog`, щоб перевірка лишалась офлайн. Delta-режим валідує один виклик на конкретний список змінених `.json`/`.json5`/`.yml`/`.yaml`/`.toml`-файлів; full-режим — по одному виклику `bunx v8r <glob>` на кожен тип розширення (v8r падає з кодом **98**, якщо переданий glob порожній, — саме тому не можна об'єднати всі розширення в один виклик).
+
+Якщо для файлу немає запису в локальному каталозі, v8r іде мережевим fallback на `schemastore.org` — це не блокує прогін, але свідчить, що каталог варто розширити.
+
+### `.v8rignore`
+
+У корені проєкту має бути **`.v8rignore`**: для JSON без стабільної схеми в Schema Store перевірка інакше завершується помилкою. Мінімум виключи **`.vscode/extensions.json`** і **`.vscode/settings.json`** (немає стабільної схеми в каталозі) — це перевіряється окремо, FS-existence-концерном `text/formatting`.
+
+```text title=".v8rignore"
+.vscode/extensions.json
+.vscode/settings.json
+.git/**
+```
+
+Не розширюй ignore, щоб приховати проблеми там, де схема є. За потреби додай **`.git/**`** (службові JSON під `.git`) та інші проєктні JSON без стабільної схеми в ланцюжку v8r (наприклад `.zed/settings.json`).
+
+### Запуск без обгортки
+
+Чотири виклики `(bunx v8r "<glob>" || [ $? -eq 98 ])` для **`**/*.json`**, **`**/*.yml`**, **`**/*.yaml`**, **`**/*.toml`** (за потреби окремо **json5**). Враховує `.gitignore`. Для власного каталогу схем — прапорець [`--catalogs`](https://chris48s.github.io/v8r/usage-examples/#using-a-custom-catlog).

package/rules/vue/composition-api/composition-api.mdc

@@ -0,0 +1,82 @@
+## Найкращі практики Vue 3 Composition API
+
+```javascript
+const vue3CompositionApiBestPractices = [
+  'Використовуй функцію setup() для логіки компонента',
+  'Реалізуй computed змінні через $computed()',
+  'Реалізуй ref змінні через $ref',
+  'Використовуй watch і watchEffect для побічних ефектів',
+  'Підключай lifecycle hooks: onMounted, onUpdated тощо',
+  'Для глибоко вкладених залежностей використовуй composables, props/emits або store'
+  'не використовуй provide/inject для залежностей'
+]
+```
+
+### Патерни та антипатерни
+
+- Для глибоко вкладених залежностей використовуй **composables**, **props/emits** або **store**; **renderless**-компоненти / **slots** — коли логіку відділяєш від розмітки.
+- **HTTP:** окремі модулі **services** або **composables** для API; **async/await**.
+- **Події:** батько–дитина через **emits**; для не пов'язаних гілок — **store**.
+- Не мутуй **props** напряму — оновлення через подію вгору або v-model.
+- Обмежуй зайве в глобальному стані; локальний стан у компоненті — за замовчуванням.
+- Уникай прямої роботи з **DOM**, якщо достатньо реактивного шаблону та ref.
+
+### State management
+
+- **Single source of truth** для спільних даних: у нових проєктах на Vue 3 **Pinia** (модульні stores, actions).
+- Похідний стан — через обчислення в store або **computed** у компонентах, без «тихих» побічних ефектів у getters.
+
+### Обробка помилок
+
+- **try/catch** навколо async-операцій; зрозумілі повідомлення для користувача через notifySuccess, notifyError; логування на сервіс моніторингу за потреби.
+
+### Продуктивність
+
+- **v-for** — стабільні унікальні **`:key`**; не плутай **v-if** (умовний mount) і **v-show** (перемикання visibility).
+- **debounce/throttle** для частих подій.
+- Після ручних **addEventListener** / підписок — прибирай у **onUnmounted**.
+
+### Функції в шаблоні
+
+Виклики функцій у шаблоні дозволені **лише** в обробниках подій (`@click`, `@change` тощо). У всіх інших місцях — `v-if`, `v-show`, атрибутах (`:prop`), інтерполяціях (`{{ }}`) — замінюй функції на `computed`-властивості: функція виконується при **кожному** render-і, тоді як `computed` кешується і перераховується лише при зміні залежностей.
+
+```vue
+<!-- ❌ функція в умові, атрибуті та інтерполяції -->
+<q-item v-if="getItems(order).length" :label="getLabel(item)">
+  {{ formatName(user) }}
+</q-item>
+
+<!-- ✅ реактивні змінні / computed / props -->
+<q-item v-if="itemsMap[order.id].length" :label="item.label">
+  {{ user.displayName }}
+</q-item>
+<!-- обробник події — виклик функції дозволений -->
+<q-btn @click="doSomething(item)" />
+```
+
+### Безпека
+
+- Не довіряй **v-html** без санітизації; для форм/API — **CSRF**-захист за потреби; валідація **на сервері** обов'язкова.
+
+### Приклад компонента
+
+```javascript
+// Приклад Vue 3 компонента з Composition API
+import { computed, onMounted } from 'vue'
+
+export default {
+  setup() {
+    const count = $ref(0)
+    const doubleCount = $computed(() => count * 2)
+
+    onMounted(() => {
+      console.log('Компонент змонтовано')
+    })
+
+    return {
+      count,
+      doubleCount
+    }
+  }
+}
+```

package/rules/vue/composition-api/concern.json

@@ -0,0 +1,3 @@
+{
+  "$schema": "https://unpkg.com/@7n/rules/schemas/concern.json"
+}

package/rules/vue/main.mdc

@@ -15,4 +15,4 @@ Rego-перевірки (запускаються через `npx @7n/rules fix
 
 ## Перевірка
 
-`npx @7n/rules fix vue` — перевіряє залежності, `vite.config`, наявність **`src/vite-env.d.ts`** з `/// <reference types="vite/client" />` та **`jsconfig.json`** у корені Vue-пакета; обходить джерела Vue-пакета (`.vue`, `.ts`, `.js` тощо) на заборонені value-імпорти з модуля `vue` (дозволені лише type-only та side-effect `import 'vue'`) і додатково сканує `.vue` SFC на імпорти Node-нативних модулів (`node:*` префікс або bare-ім'я вбудованого модуля Node — `fs`, `path`, `timers/promises` тощо). Імпорти аналізуються через **oxc-parser** (`module.staticImports`); для `.vue` вміст `<script>` витягується з SFC, далі той самий парсер (логіка в `npm/rules/vue/js/packages/vue-forbidden-imports.mjs`).
+`npx @7n/rules fix vue` — перевіряє залежності, `vite.config`, наявність **`src/vite-env.d.ts`** з `/// <reference types="vite/client" />` та **`jsconfig.json`** у корені Vue-пакета; обходить джерела Vue-пакета (`.vue`, `.ts`, `.js` тощо) на заборонені value-імпорти з модуля `vue` (дозволені лише type-only та side-effect `import 'vue'`) і додатково сканує `.vue` SFC на імпорти Node-нативних модулів (`node:*` префікс або bare-ім'я вбудованого модуля Node — `fs`, `path`, `timers/promises` тощо). Імпорти аналізуються через **oxc-parser** (`module.staticImports`); для `.vue` вміст `<script>` витягується з SFC, далі той самий парсер (логіка в `npm/rules/vue/lib/vue-forbidden-imports.mjs`).

package/rules/vue/nheader-layout/concern.json

@@ -0,0 +1,3 @@
+{
+  "$schema": "https://unpkg.com/@7n/rules/schemas/concern.json"
+}