@7n/rules 1.0.0

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

@@ -0,0 +1,31 @@
+---
+type: JS Module
+title: main.mjs
+resource: npm/rules/text/run-shellcheck/main.mjs
+docgen:
+  crc: e365b165
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+  issues: judge:inaccurate:0.99
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+## Огляд
+
+Цей механізм сканує всі відстежені (`git ls-files` з `pathspec :(glob)`) та невідстежені (`globSync` з виключенням `node_modules`) shell-скрипти (`*.sh`) у робочому дереві. Він реалізує двохетапний процес: спочатку автоматично застосовує виправлення потенційних порушень за допомогою `shellcheck` та `patch` (що використовує формат `diff`), а потім виконує фінальну валідацію кожного скрипта за допомогою звичайного `shellcheck`. Якщо `shellcheck` не знайдений або відсутній `patch`, процес завершується з відповідними підказками.
+
+## Поведінка
+
+Поведінка:
+listShellScriptPaths знаходить відносні шляхи до всіх відстежуваних або знайдених скриптів з розширенням .sh у робочому дереві, виключаючи каталоги node_modules.
+runShellcheckText виконує перевірку shell-скриптів: спочатку намагається автоматично виправити можливі помилки за допомогою `shellcheck` у режимі `diff` та інструменту `patch`, а потім проводить фінальний звітний прогін для всіх знайдених файлів.
+
+## Публічний API
+
+listShellScriptPaths — надає шляхи до скриптів командного рядка, які мають бути перевірені.
+runShellcheckText — виконує перевірку скриптів на відповідність стандартам ShellCheck із автоматичним виправленням.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).
+- Свідомо пропускає шляхи: `node_modules`.

package/rules/text/run-shellcheck/fix-run-shellcheck.mjs

@@ -0,0 +1,44 @@
+/**
+ * T0-autofix для `text/run-shellcheck` — `shellcheck -f diff` + `patch`, перенесено з колишнього
+ * `text/check/fix-check.mjs` (spec docs/specs/2026-07-02-text-check-per-file-split-design.md §1).
+ * `runShellcheckText(cwd, false)` сама ре-аналізує (diff+patch по колу) — per-violation дані тут
+ * не потрібні, лише факт "shellcheck щось знайшов".
+ */
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+
+import { listShellScriptPaths, runShellcheckText } from './main.mjs'
+
+/**
+ * Вміст файлу або null, якщо не читається.
+ * @param {string} abs абсолютний шлях
+ * @returns {string|null} вміст або null
+ */
+function readOrNull(abs) {
+  try {
+    return readFileSync(abs, 'utf8')
+  } catch {
+    return null
+  }
+}
+
+/** @type {import('../../../scripts/lib/lint-surface/types.mjs').T0Pattern[]} */
+export const patterns = [
+  {
+    id: 'text-shellcheck-fix',
+    standalone: true, // §8 Phase 2: shellcheck diff+patch цикл сам ре-аналізує, test() не потрібен
+    test: violations => violations.some(v => v.reason === 'shellcheck'),
+    apply: (violations, ctx) => {
+      const files = listShellScriptPaths(ctx.cwd)
+      if (files.length === 0) return { touchedFiles: [] }
+      const abs = files.map(f => resolve(ctx.cwd, f))
+      const before = new Map(abs.map(a => [a, readOrNull(a)]))
+      runShellcheckText(ctx.cwd, false)
+      const touchedFiles = abs.filter(a => readOrNull(a) !== before.get(a))
+      for (const a of touchedFiles) ctx.recordWrite?.(a)
+      return touchedFiles.length > 0
+        ? { touchedFiles, message: `shellcheck --fix: ${touchedFiles.length} файл(ів)` }
+        : { touchedFiles: [] }
+    }
+  }
+]

package/rules/text/run-shellcheck/main.mjs

@@ -0,0 +1,245 @@
+/**
+ * Запуск shellcheck у ланцюжку lint-text: спочатку авто-застосування виправлень, потім фінальна перевірка.
+ *
+ * ShellCheck не має прапорця «--fix»; для виправлень, які інструмент уміє запропонувати, використовується
+ * формат виводу `diff` і застосування патчу через `patch -p1` у корені проєкту (шляхи у unified diff від ShellCheck
+ * узгоджуються з цим режимом).
+ *
+ * Якщо `shellcheck` відсутній у PATH, скрипт завершується з кодом 1 і друкує підказки встановлення
+ * (macOS: Homebrew; Debian/Ubuntu: apt; Arch: pacman). Аналогічно для `patch`, якщо його немає
+ * (рідко на macOS/Linux).
+ *
+ * Список файлів: у git-робочому дереві — `git ls-files` з pathspec `:(glob)` для всіх tracked `*.sh`;
+ * інакше — `globSync` з виключенням `node_modules`. Якщо скриптів не знайдено — вихід 0.
+ *
+ * Після циклу авто-виправлень виконується звичайний `shellcheck` по всіх зібраних файлах; будь-яке
+ * попередження чи помилка — ненульовий код виходу.
+ */
+import { spawnSync } from 'node:child_process'
+import { globSync } from 'node:fs'
+import { resolve } from 'node:path'
+
+import { isRunAsCli } from '../../../scripts/cli-entry.mjs'
+import { resolveCmd } from '../../../scripts/utils/resolve-cmd.mjs'
+import { createViolationReporter } from '../../../scripts/lib/lint-surface/violation-reporter.mjs'
+
+/** Розширення shell-скриптів — фільтр delta-списку файлів у `lint(ctx)`. */
+const SH_EXT_RE = /\.sh$/u
+
+/** Підрядок у stderr ShellCheck, коли є зауваження, але без авто-виправлення у форматі diff. */
+const NON_AUTOFIXABLE_HINT = 'none were auto-fixable'
+
+/** Максимум ітерацій `diff`+`patch` на один файл (захист від зациклення). */
+const MAX_FIX_ROUNDS_PER_FILE = 32
+
+/**
+ * Друкує підказки встановлення shellcheck у stderr.
+ * @returns {void}
+ */
+function printShellcheckInstallHints() {
+  process.stderr.write(
+    [
+      '❌ shellcheck не знайдено в PATH.',
+      'Встанови інструмент і повтори lint-text:',
+      '  macOS:    brew install shellcheck',
+      '  Debian/Ubuntu: sudo apt-get install -y shellcheck',
+      '  Arch:     sudo pacman -S shellcheck',
+      ''
+    ].join('\n')
+  )
+}
+
+/**
+ * Друкує підказку для відсутнього patch.
+ * @returns {void}
+ */
+function printPatchInstallHints() {
+  process.stderr.write(
+    [
+      '❌ patch не знайдено в PATH (потрібен для застосування diff від shellcheck).',
+      '  macOS: patch зазвичай уже є; Debian/Ubuntu: sudo apt-get install -y patch',
+      ''
+    ].join('\n')
+  )
+}
+
+/**
+ * Повертає відносні шляхи до shell-скриптів для перевірки.
+ * @param {string} cwd корінь проєкту
+ * @returns {string[]} відсортований масив шляхів відносно cwd
+ */
+export function listShellScriptPaths(cwd) {
+  const gitPath = resolveCmd('git')
+  if (gitPath) {
+    const gitOk = spawnSync(gitPath, ['rev-parse', '--is-inside-work-tree'], {
+      cwd,
+      encoding: 'utf8',
+      env: process.env
+    })
+    if (gitOk.status === 0 && gitOk.stdout.trim() === 'true') {
+      const ls = spawnSync(gitPath, ['ls-files', '-z', '--', ':(glob)**/*.sh'], {
+        cwd,
+        encoding: 'utf8',
+        env: process.env
+      })
+      if (ls.status !== 0) {
+        return []
+      }
+      const files = ls.stdout.split('\0').filter(Boolean)
+      return [...new Set(files)].toSorted()
+    }
+  }
+
+  const fromGlob = globSync('**/*.sh', {
+    cwd,
+    exclude: p => p.includes('node_modules') || p.startsWith(`node_modules/`) || p.split('/').includes('node_modules')
+  })
+  return [...new Set(fromGlob.map(p => p.replaceAll('\\', '/')))].toSorted()
+}
+
+/**
+ * Запускає shellcheck із авто-виправленнями і фінальною перевіркою.
+ * @param {string} [cwd] робочий каталог (за замовчуванням `process.cwd()`)
+ * @param {boolean} [readOnly] true → пропустити авто-фікс (diff+patch), лише фінальна перевірка
+ * @param {string[]} [scopeFiles] явний перелік файлів (delta) — якщо не задано, шукає всі `*.sh` через `listShellScriptPaths`
+ * @returns {number} 0 — OK; 1 — помилка середовища або залишкові зауваження shellcheck
+ */
+export function runShellcheckText(cwd, readOnly, scopeFiles) {
+  const root = resolve(cwd ?? process.cwd())
+  const shellcheck = resolveCmd('shellcheck')
+  if (!shellcheck) {
+    printShellcheckInstallHints()
+    return 1
+  }
+  // patch потрібен лише для авто-фіксу (diff+patch); у read-only його відсутність не блокує детект.
+  const patchBin = readOnly ? null : resolveCmd('patch')
+  if (!readOnly && !patchBin) {
+    printPatchInstallHints()
+    return 1
+  }
+
+  const files = scopeFiles ?? listShellScriptPaths(root)
+  if (files.length === 0) {
+    return 0
+  }
+
+  if (!readOnly) {
+    for (const rel of files) {
+      const fixCode = autofixOneFile(shellcheck, /** @type {string} */ (patchBin), root, rel)
+      if (fixCode !== 0) return fixCode
+    }
+  }
+
+  return runFinalShellcheck(shellcheck, files, root)
+}
+
+/**
+ * Detector text/run-shellcheck: read-only shellcheck по `ctx.files` (delta) або по всіх `*.sh` (full).
+ * @param {import('../../../scripts/lib/lint-surface/types.mjs').LintContext} ctx контекст lint-прогону
+ * @returns {import('../../../scripts/lib/lint-surface/types.mjs').LintResult} результат detector-а
+ */
+export function lint(ctx) {
+  const reporter = createViolationReporter(ctx)
+  const { fail } = reporter
+  const scopeFiles = ctx.files === undefined ? undefined : ctx.files.filter(f => SH_EXT_RE.test(f))
+  if (scopeFiles !== undefined && scopeFiles.length === 0) return reporter.result()
+
+  const code = runShellcheckText(ctx.cwd, true, scopeFiles)
+  if (code !== 0) fail('shellcheck знайшов порушення у *.sh (text.mdc)', 'shellcheck')
+  return reporter.result()
+}
+
+/**
+ * Запускає до `MAX_FIX_ROUNDS_PER_FILE` ітерацій `shellcheck -f diff` + `patch` для одного файла.
+ * Виходить з 0 у випадках: shellcheck повернув 0, нема autofixable, або порожній diff.
+ * @param {string} shellcheck абсолютний шлях до shellcheck
+ * @param {string} patchBin абсолютний шлях до patch
+ * @param {string} root абсолютний робочий каталог (cwd для spawn)
+ * @param {string} rel відносний шлях файла від `root`
+ * @returns {number} 0 — OK; 1 — помилка spawn або patch
+ */
+function autofixOneFile(shellcheck, patchBin, root, rel) {
+  for (let round = 0; round < MAX_FIX_ROUNDS_PER_FILE; round++) {
+    const diffResult = spawnSync(shellcheck, ['-f', 'diff', rel], {
+      cwd: root,
+      encoding: 'utf8',
+      env: process.env,
+      maxBuffer: 10 * 1024 * 1024
+    })
+    if (diffResult.error) {
+      process.stderr.write(`${diffResult.error.message}\n`)
+      return 1
+    }
+    if (shouldStopAutofixLoop(diffResult)) return 0
+    const patchCode = applyShellcheckDiff(patchBin, root, rel, diffResult.stdout ?? '')
+    if (patchCode !== 0) return patchCode
+  }
+  return 0
+}
+
+/**
+ * Чи треба зупинити цикл авто-фіксів: shellcheck повернув 0, або у stderr є пометка
+ * `none were auto-fixable`, або stdout порожній (нема дифу для застосування).
+ * @param {{ status: number | null, stdout?: string | null, stderr?: string | null }} diffResult результат spawnSync
+ * @returns {boolean} true — більше нічого фіксити
+ */
+function shouldStopAutofixLoop(diffResult) {
+  const code = diffResult.status ?? 1
+  if (code === 0) return true
+  const out = (diffResult.stdout ?? '').trim()
+  const err = (diffResult.stderr ?? '').trim()
+  return err.includes(NON_AUTOFIXABLE_HINT) || !out
+}
+
+/**
+ * Застосовує `shellcheck -f diff`-вивід через `patch -p1`. На помилку виливає stdout/stderr від patch
+ * у `process.stderr` (щоб користувач бачив, чому не застосувалося) і повертає 1.
+ * @param {string} patchBin абсолютний шлях до patch
+ * @param {string} root cwd для spawn
+ * @param {string} rel відносний шлях для повідомлення про помилку
+ * @param {string} diffStdout вміст unified-diff від shellcheck (input для patch)
+ * @returns {number} 0 — застосовано; 1 — помилка
+ */
+function applyShellcheckDiff(patchBin, root, rel, diffStdout) {
+  const patchRun = spawnSync(patchBin, ['-p1'], {
+    cwd: root,
+    input: diffStdout,
+    encoding: 'utf8',
+    env: process.env
+  })
+  if (patchRun.status === 0) return 0
+  if (patchRun.stderr?.length) process.stderr.write(patchRun.stderr)
+  if (patchRun.stdout?.length) process.stderr.write(patchRun.stdout)
+  process.stderr.write(`run-shellcheck-text: patch не застосував diff для ${rel}\n`)
+  return 1
+}
+
+/**
+ * Фінальний прогон `shellcheck` по всіх файлах — без `-f diff`, щоб отримати звичайний звіт.
+ * Будь-який ненульовий код shellcheck-а пробрасує як 1 (з виводом stdout/stderr на користувацькі stream-и).
+ * @param {string} shellcheck абсолютний шлях до shellcheck
+ * @param {string[]} files відносні шляхи файлів для перевірки
+ * @param {string} root cwd для spawn
+ * @returns {number} 0 — чисто; 1 — помилка spawn або зауваження shellcheck
+ */
+function runFinalShellcheck(shellcheck, files, root) {
+  const finalRun = spawnSync(shellcheck, files, {
+    cwd: root,
+    encoding: 'utf8',
+    env: process.env,
+    maxBuffer: 10 * 1024 * 1024,
+    stdio: ['ignore', 'pipe', 'pipe']
+  })
+  if (finalRun.error) {
+    process.stderr.write(`${finalRun.error.message}\n`)
+    return 1
+  }
+  if (finalRun.status === 0) return 0
+  if (finalRun.stdout?.length) process.stdout.write(finalRun.stdout)
+  if (finalRun.stderr?.length) process.stderr.write(finalRun.stderr)
+  return 1
+}
+
+if (isRunAsCli(import.meta.url)) {
+  process.exitCode = runShellcheckText()
+}

package/rules/text/run-v8r/concern.json

@@ -0,0 +1,7 @@
+{
+  "$schema": "https://unpkg.com/@7n/rules/schemas/concern.json",
+  "lint": {
+    "scope": "per-file",
+    "glob": ["**/*.json", "**/*.json5", "**/*.yml", "**/*.yaml", "**/*.toml"]
+  }
+}

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

@@ -0,0 +1,11 @@
+---
+type: Directory Index
+title: npm/rules/text/run-v8r
+resource: npm/rules/text/run-v8r/
+---
+
+# npm/rules/text/run-v8r
+
+| Файл                | Тип       |
+| ------------------- | --------- |
+| [main.mjs](main.md) | JS Module |

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

@@ -0,0 +1,40 @@
+---
+type: JS Module
+title: main.mjs
+resource: npm/rules/text/run-v8r/main.mjs
+docgen:
+  crc: f6f78d26
+---
+
+## Огляд
+
+Пакетна перевірка синтаксису та відповідності JSON-схем для файлів `json`/`json5`/`yaml`/`yml`/`toml` за один виклик `lint-text`, замість п'яти окремих `v8r`-процесів (по одному на розширення, бо `v8r` завершується кодом 98, якщо хоч один із переданих `glob` не знаходить файлів). Каталог схем `@7n/rules` (`npm/schemas/v8r-catalog.json`) описує локальні (не-http) схеми як шляхи ВІДНОСНО `npm/schemas/` — усі власні (`n-rules.json`, `rule-meta.json`, `skill-meta.json`, `concern.json`, `target.json`) і сторонні (`npm/schemas/vendor/`: `package.json`, `tsconfig.json`, `oxlintrc.json`, `cspell.json`, `knip.json`, `jscpd.json` тощо) схеми вендорені — `v8r` ніколи не фетчить їх по мережі. Вендоровані схеми self-contained: усі `$ref` внутрішні (зовнішні `v8r` резолвив би через `got` відносно `$id` — мережею на кожен прогін); зовнішні залежності інлайняться при вендорингу (у `vendor/package.json` вкладено eslintrc/prettierrc/ava/… як `definitions.vendored-<name>`), інваріант закріплено guard-тестом `npm/rules/text/tests/run-v8r-catalog.test.mjs`.
+
+Перед кожним запуском модуль матеріалізує тимчасовий v8r-конфіг-файл із полем `customCatalog` (абсолютні локальні шляхи, обчислені через `import.meta.url`) і передає його через змінну середовища `V8R_CONFIG_FILE`, а не через прапор `-c` — `-c`-каталог `v8r` на кожен файл валідує проти `schema-catalog.json`-метасхеми, яка вимагає `format: "uri"` для `url`; абсолютний локальний шлях цій вимозі не відповідає, а `file://`-URI відповідав би формату, але `v8r` фетчить `url` через `got` (лише http/https). `customCatalog` (ключ `location`, без `format: "uri"`-обмеження) пропускає цю метавалідацію.
+
+## Поведінка
+
+- `DEFAULT_V8R_GLOBS` — стандартні glob-и для `.json`, `.json5`, `.yml`, `.yaml`, `.toml`.
+- `V8R_CATALOG_PATH` — абсолютний шлях до джерельного `npm/schemas/v8r-catalog.json`.
+- `RESOLVED_V8R_CONFIG_PATH` — фіксований шлях у `os.tmpdir()` для тимчасового v8r-конфігу.
+- `V8R_CACHE_TTL_SECONDS` — TTL HTTP-кешу v8r (доба замість дефолтних 600 с): fallback-фетчі schemastore не повторюються на кожен прогін.
+- `resolveCustomCatalogSchemas()` — читає джерельний каталог, повертає масив схем у форматі v8r `customCatalog.schemas` (ключ `location`, локальні шляхи — абсолютні).
+- `writeResolvedV8rConfig()` — записує `{ cacheTtl, customCatalog: { schemas } }` у `RESOLVED_V8R_CONFIG_PATH` (побічний ефект: файлова операція запису, поза rollback-механізмом лінт-пайплайна).
+- `runV8rWithGlobs(globs?)` — послідовно запускає `v8r` для кожного glob-у з `V8R_CONFIG_FILE`, вказаним на резольвнутий конфіг; при коді 0/98 вивід приховано, інакше друкується й повертається код першого невдалого прогону.
+- `runV8rWithFiles(files)` — delta-режим: один запуск `v8r` по конкретних існуючих шляхах (код 98 неможливий), порожній список — одразу 0.
+- `warnAboutRemoteSchemaFallback(stderrText)` — парсить stderr `v8r` і на кожен файл, чию схему знайдено мережевим fallback-ом (schemastore, не customCatalog), друкує в stdout пораду додати схему в каталог.
+- `lint(ctx)` — detector `text/run-v8r`: `ctx.files` → delta по відфільтрованих розширеннях, без `ctx.files` → full за `DEFAULT_V8R_GLOBS`.
+
+## Публічний API
+
+- `DEFAULT_V8R_GLOBS`, `V8R_CATALOG_PATH`, `RESOLVED_V8R_CONFIG_PATH`, `V8R_CACHE_TTL_SECONDS` — константи.
+- `resolveCustomCatalogSchemas()` — обчислені схеми customCatalog.
+- `writeResolvedV8rConfig()` — матеріалізація тимчасового конфігу, повертає його шлях.
+- `runV8rWithGlobs(globs?)`, `runV8rWithFiles(files)` — точки входу перевірки (full/delta).
+- `warnAboutRemoteSchemaFallback(stderrText)` — попередження про мережевий fallback схем.
+- `lint(ctx)` — інтеграція в lint-пайплайн.
+
+## Гарантії поведінки
+
+- Записує один тимчасовий JSON-файл у `os.tmpdir()` (`RESOLVED_V8R_CONFIG_PATH`) на кожен виклик `runV8rWithGlobs`/`runV8rWithFiles`; жодних записів поза tmpdir і в цільове дерево проєкту.
+- Схеми з каталогу — локальні файли (`npm/schemas/` + `npm/schemas/vendor/`), без мережевих фетчів. Для файлів поза каталогом v8r іде по мережевий fallback-каталог schemastore (мережа — передумова роботи, офлайн-захисту нема); повторні фетчі гасяться HTTP-кешем v8r із TTL `V8R_CACHE_TTL_SECONDS`.

package/rules/text/run-v8r/main.mjs

@@ -0,0 +1,266 @@
+/**
+ * Тихий запуск v8r для усіх типів файлів, які підтримує v8r (json, json5, yaml, yml, toml).
+ *
+ * Один виклик цього скрипта з `lint-text` замість чотирьох окремих викликів v8r: під капотом для
+ * кожного glob окремий `bunx v8r`, бо v8r у одному процесі падає з кодом 98, якщо хоч один із
+ * переданих глобів не знаходить файлів — тоді решта розширень не перевіряються.
+ *
+ * Каталог схем `@7n/rules` (`v8r-catalog.json` у каталозі `schemas` пакета) вказує локальні
+ * (не-http) схеми як шляхи ВІДНОСНО `npm/schemas/` (наприклад `"n-rules.json"`,
+ * `"vendor/tsconfig.json"`) — так каталог лишається портативним у репозиторії. Ці схеми вендорені
+ * в `npm/schemas/` (власні) і `npm/schemas/vendor/` (сторонні: package.json, tsconfig, oxlintrc,
+ * cspell тощо) — v8r ніколи не фетчить їх по мережі. Вендоровані схеми мають бути self-contained:
+ * усі `$ref` — внутрішні (`#…`), бо зовнішні v8r резолвить через `got` (лише http/https) відносно
+ * `$id` схеми, тобто мережею на кожен прогін; зовнішні залежності інлайняться при вендорингу
+ * (наприклад, у `vendor/package.json` вкладено eslintrc/prettierrc/ava/… як
+ * `definitions.vendored-<name>`). Інваріант — під guard-тестом у
+ * `npm/rules/text/tests/run-v8r-catalog.test.mjs`.
+ *
+ * Передаємо каталог у v8r НЕ через `-c` (файловий шлях), а через `customCatalog` у тимчасовому
+ * v8r-конфіг-файлі (`V8R_CONFIG_FILE`): `-c` змушує v8r на кожен файл валідувати сам каталог проти
+ * schema-catalog.json мета-схеми, яка вимагає `format: "uri"` для `url` — абсолютний локальний шлях
+ * (потрібен, бо v8r резолвить `url` відносно CWD процесу, не каталогу) цій вимозі не відповідає,
+ * а `file://`-URI задовольнив би формат, але v8r фетчить `url` через `got` (лише http/https, без
+ * підтримки `file:`) — глухий кут. `customCatalog` (ключ `location`, не `url`) не має format:uri
+ * обмеження і геть пропускає цю мета-валідацію (v8r код: `if (!rec.catalog) {...validate...}` —
+ * для `customCatalog` `rec.catalog` завжди truthy).
+ *
+ * Опційно можна передати власні glob-и як аргументи; якщо їх немає — типові для `.json`, `.json5`,
+ * `.yml`, `.yaml`, `.toml` у дереві проєкту.
+ *
+ * Якщо код виходу 0 або 98 (успіх або порожній glob), вивід v8r не показується; інакше без
+ * `--verbose` друкуються лише рядки `✖ …` (конкретні помилки валідації), а `ℹ`-шум v8r
+ * (Pre-warming the cache, Processing <file>, Found schema in …, Validating … / ✔ … is valid)
+ * гейтується за `--verbose` — той самий підхід, що й для інших зовнішніх тулів лінт-конвеєра
+ * (zizmor/cspell/knip/kubeconform тощо, fix(lint) #42). Процес завершується з тим самим кодом,
+ * що й перший невдалий v8r.
+ *
+ * v8r завжди дописує `https://www.schemastore.org/api/json/catalog.json` останнім fallback-
+ * каталогом (безумовно, без опції вимкнути) — якщо файл не збігається з нашим `customCatalog`, v8r
+ * піде по мережу за ним. Мережа — передумова коректної роботи (офлайн-захисту нема), але щоб не
+ * фетчити те саме на кожен прогін, конфіг задає `cacheTtl` доба замість дефолтних 600 с (v8r кешує
+ * HTTP-відповіді у flat-cache в tmpdir). Fallback НЕ блокується: файл валідується, а `main.mjs`
+ * парсить stderr v8r (рядки `ℹ Found schema in <url>` — цей `info`-рівень v8r друкує завжди,
+ * незалежно від verbosity) і виводить у stdout окреме попередження на кожен такий файл із порадою
+ * додати схему в `npm/schemas/v8r-catalog.json`.
+ */
+import { spawnSync } from 'node:child_process'
+import { existsSync, readFileSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { dirname, isAbsolute, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import { isRunAsCli } from '../../../scripts/cli-entry.mjs'
+import { resolveCmd } from '../../../scripts/utils/resolve-cmd.mjs'
+import { createViolationReporter } from '../../../scripts/lib/lint-surface/violation-reporter.mjs'
+
+/** Розширення, які валідує v8r — фільтр delta-списку файлів у `lint(ctx)`. */
+const V8R_EXT_RE = /\.(?:json|json5|ya?ml|toml)$/iu
+
+/** Типові glob-и для форматів, які обробляє v8r (див. опис CLI v8r). */
+export const DEFAULT_V8R_GLOBS = ['**/*.json', '**/*.json5', '**/*.yml', '**/*.yaml', '**/*.toml']
+
+/** Абсолютний шлях до `schemas/v8r-catalog.json` у корені пакета `@7n/rules` (`npm/schemas/`). */
+export const V8R_CATALOG_PATH = join(dirname(fileURLToPath(import.meta.url)), '../../../schemas/v8r-catalog.json')
+
+/** Шлях до тимчасового v8r-конфіг-файлу з `customCatalog` — генерується щоразу перед запуском. */
+export const RESOLVED_V8R_CONFIG_PATH = join(tmpdir(), 'n-rules-v8r-config.resolved.json')
+
+const REMOTE_URL_RE = /^https?:\/\//u
+
+/**
+ * Чи є значення локальним шляхом (не http/https-адресою).
+ * @param {string} url значення поля `url` у записі джерельного каталогу
+ * @returns {boolean} true — локальний шлях, false — http(s)-адреса
+ */
+function isLocalSchemaPath(url) {
+  return !REMOTE_URL_RE.test(url)
+}
+
+/**
+ * Читає джерельний каталог (`V8R_CATALOG_PATH`, ключ `url`, локальні шляхи відносні до
+ * `npm/schemas/`) і повертає масив схем у форматі v8r `customCatalog.schemas` (ключ `location`,
+ * локальні шляхи — абсолютні, обчислені через `import.meta.url`, тож коректні незалежно від CWD
+ * процесу й від того, чи це repo-dev копія, чи встановлена в `node_modules/@7n/rules`).
+ * @returns {Array<{name: string, description?: string, location: string, fileMatch: string[]}>} схеми customCatalog
+ */
+export function resolveCustomCatalogSchemas() {
+  const raw = readFileSync(V8R_CATALOG_PATH, 'utf8')
+  const catalog = JSON.parse(raw)
+  const schemasDir = dirname(V8R_CATALOG_PATH)
+  return catalog.schemas.map(({ url, ...rest }) => ({
+    ...rest,
+    location: isLocalSchemaPath(url) && !isAbsolute(url) ? join(schemasDir, url) : url
+  }))
+}
+
+/**
+ * TTL HTTP-кешу v8r (секунди): доба замість дефолтних 600 с — fallback-фетчі schemastore-каталогу
+ * для незматчених файлів і remote-схеми не тягнуться мережею на кожен прогін (flat-cache у tmpdir).
+ */
+export const V8R_CACHE_TTL_SECONDS = 86_400
+
+/**
+ * Матеріалізує тимчасовий v8r-конфіг (`{ cacheTtl, customCatalog: { schemas } }`) у
+ * `RESOLVED_V8R_CONFIG_PATH`.
+ * @returns {string} шлях до записаного файлу
+ */
+export function writeResolvedV8rConfig() {
+  const config = { cacheTtl: V8R_CACHE_TTL_SECONDS, customCatalog: { schemas: resolveCustomCatalogSchemas() } }
+  writeFileSync(RESOLVED_V8R_CONFIG_PATH, JSON.stringify(config), 'utf8')
+  return RESOLVED_V8R_CONFIG_PATH
+}
+
+const PROCESSING_LINE_RE = /^ℹ Processing (.+)$/u
+const FOUND_REMOTE_SCHEMA_RE = /^ℹ Found schema in (https?:\/\/\S+)/u
+const FAILURE_LINE_RE = /^✖ .+$/mu
+
+/**
+ * Витягує лише рядки `✖ …` (конкретні помилки валідації) з raw stdout v8r — без `ℹ`-шуму
+ * (Pre-warming the cache, Processing <file>, Found schema in …) і без `✔ … is valid` по
+ * пройдених файлах. Використовується для non-verbose підсумку при невдалому прогоні.
+ * @param {string} stdoutText захоплений stdout одного запуску v8r
+ * @returns {string} рядки `✖ …`, з'єднані `\n` (порожній рядок, якщо збігів нема)
+ */
+export function extractFailureLines(stdoutText) {
+  return (stdoutText.match(FAILURE_LINE_RE) ?? []).join('\n')
+}
+
+/**
+ * Парсить stderr v8r (рядки `ℹ Processing <file>` / `ℹ Found schema in <url>`, які v8r друкує
+ * завжди на info-рівні незалежно від verbosity) і для кожного файлу, чию схему знайдено через
+ * мережевий fallback (schemastore.org, а не наш `customCatalog`), пише в stdout попередження.
+ * @param {string} stderrText захоплений stderr одного запуску v8r
+ * @returns {void}
+ */
+export function warnAboutRemoteSchemaFallback(stderrText) {
+  let currentFile = null
+  for (const line of stderrText.split('\n')) {
+    const processingMatch = PROCESSING_LINE_RE.exec(line)
+    if (processingMatch) {
+      currentFile = processingMatch[1]
+      continue
+    }
+    const remoteMatch = FOUND_REMOTE_SCHEMA_RE.exec(line)
+    if (remoteMatch && currentFile) {
+      process.stdout.write(
+        `⚠ run-v8r: ${currentFile} — схему знайдено через мережевий fallback (${remoteMatch[1]}), а не в локальному каталозі @7n/rules. Додай схему в npm/schemas/v8r-catalog.json (+ npm/schemas/vendor/ за потреби), щоб прогін лишався офлайн.\n`
+      )
+    }
+  }
+}
+
+/**
+ * Один виклик `bun x v8r <targets...>` з підготовленим `customCatalog`-конфігом.
+ * @param {string[]} targets glob-и або конкретні шляхи файлів
+ * @param {string} configPath шлях до `V8R_CONFIG_FILE`
+ * @param {boolean} [verbose] друкувати повний raw stdout/stderr v8r при помилці; інакше — лише
+ *   рядки `✖ …` без `ℹ`-шуму (Pre-warming the cache, Processing <file>, Found schema in …)
+ * @returns {{ exitError: true } | { exitError: false, code: number }} помилка spawn або код v8r (0/98 — трактує викликач)
+ */
+function runOneV8rInvocation(targets, configPath, verbose = false) {
+  const bunPath = resolveCmd('bun') ?? process.execPath
+  const result = spawnSync(bunPath, ['x', 'v8r', ...targets], {
+    encoding: 'utf8',
+    maxBuffer: 50 * 1024 * 1024,
+    shell: false,
+    stdio: ['ignore', 'pipe', 'pipe'],
+    env: { ...process.env, V8R_CONFIG_FILE: configPath }
+  })
+
+  if (result.error) {
+    process.stderr.write(`${result.error.message}\n`)
+    return { exitError: true }
+  }
+
+  warnAboutRemoteSchemaFallback(result.stderr ?? '')
+
+  const exitCode = result.status ?? 1
+  if (exitCode !== 0 && exitCode !== 98) {
+    if (verbose) {
+      if (result.stdout?.length) process.stdout.write(result.stdout)
+      if (result.stderr?.length) process.stderr.write(result.stderr)
+    } else {
+      const failureLines = extractFailureLines(result.stdout ?? '')
+      if (failureLines.length) process.stdout.write(`${failureLines}\n`)
+    }
+  }
+  return { exitError: false, code: exitCode }
+}
+
+/**
+ * Запускає послідовні виклики v8r по glob-ам (full-режим); не змінює process.exitCode.
+ * Один виклик на glob навмисно (не batch) — v8r падає з кодом 98, якщо хоч один переданий
+ * glob не знаходить файлів, і тоді решта розширень не перевіряються в тому ж виклику.
+ * @param {string[]} [globs] патерни; за замовчуванням DEFAULT_V8R_GLOBS
+ * @param {boolean} [verbose] друкувати повний raw вивід v8r при помилці (див. runOneV8rInvocation)
+ * @returns {number} 0 — OK, 1 — помилка spawn, 2 — немає каталогу схем, інше — код v8r
+ */
+export function runV8rWithGlobs(globs = DEFAULT_V8R_GLOBS, verbose = false) {
+  if (!existsSync(V8R_CATALOG_PATH)) {
+    process.stderr.write(
+      `run-v8r: не знайдено каталог схем за шляхом ${V8R_CATALOG_PATH} (очікується npm/schemas/v8r-catalog.json у пакеті)\n`
+    )
+    return 2
+  }
+
+  const configPath = writeResolvedV8rConfig()
+
+  for (const pattern of globs) {
+    const r = runOneV8rInvocation([pattern], configPath, verbose)
+    if (r.exitError) return 1
+    if (r.code !== 0 && r.code !== 98) return r.code
+  }
+  return 0
+}
+
+/**
+ * Запускає v8r по конкретному списку файлів (delta-режим) — один виклик, не по одному glob-у,
+ * бо кожен переданий шлях уже існує (не glob), тож код 98 "порожній glob" тут не виникає.
+ * @param {string[]} files абсолютні або відносні до cwd v8r-процесу шляхи файлів
+ * @param {boolean} [verbose] друкувати повний raw вивід v8r при помилці (див. runOneV8rInvocation)
+ * @returns {number} 0 — OK, 1 — помилка spawn, 2 — немає каталогу схем, інше — код v8r
+ */
+export function runV8rWithFiles(files, verbose = false) {
+  if (files.length === 0) return 0
+  if (!existsSync(V8R_CATALOG_PATH)) {
+    process.stderr.write(
+      `run-v8r: не знайдено каталог схем за шляхом ${V8R_CATALOG_PATH} (очікується npm/schemas/v8r-catalog.json у пакеті)\n`
+    )
+    return 2
+  }
+
+  const configPath = writeResolvedV8rConfig()
+  const r = runOneV8rInvocation(files, configPath, verbose)
+  if (r.exitError) return 1
+  return r.code === 98 ? 0 : r.code
+}
+
+/**
+ * Detector text/run-v8r: read-only v8r по `ctx.files` (delta) або за дефолтними glob-ами (full).
+ * @param {import('../../../scripts/lib/lint-surface/types.mjs').LintContext} ctx контекст lint-прогону
+ * @returns {import('../../../scripts/lib/lint-surface/types.mjs').LintResult} результат detector-а
+ */
+export function lint(ctx) {
+  const reporter = createViolationReporter(ctx)
+  const { fail } = reporter
+
+  const verbose = ctx.verbose === true
+
+  if (ctx.files === undefined) {
+    const code = runV8rWithGlobs(DEFAULT_V8R_GLOBS, verbose)
+    if (code !== 0) fail('v8r schema-валідація json/yaml/toml не пройшла (text.mdc)', 'v8r')
+    return reporter.result()
+  }
+
+  const files = ctx.files.filter(f => V8R_EXT_RE.test(f))
+  if (files.length === 0) return reporter.result()
+  const code = runV8rWithFiles(files, verbose)
+  if (code !== 0) fail('v8r schema-валідація json/yaml/toml не пройшла (text.mdc)', 'v8r')
+  return reporter.result()
+}
+
+if (isRunAsCli(import.meta.url)) {
+  const globs = process.argv.length > 2 ? process.argv.slice(2) : DEFAULT_V8R_GLOBS
+  process.exitCode = runV8rWithGlobs(globs)
+}