@7n/rules 1.8.2 → 1.8.4

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## [1.8.4] - 2026-07-17
+
+### Fixed
+
+- text/run-v8r: включати причину провалу v8r (stdout+stderr, без noise) у violation-повідомлення замість голого коду виходу
+- k8s/manifests: форматування tests/check-schema.test.mjs (oxfmt)
+
+## [1.8.3] - 2026-07-17
+
+### Changed
+
+- release: @7n/rules@1.8.2
+
 ## [1.8.2] - 2026-07-17
 
 ### Fixed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@7n/rules",
-  "version": "1.8.2",
+  "version": "1.8.4",
   "description": "CLI еталонних правил і skills (префікс n-): синк у репозиторій, дельта-lint, конформність",
   "keywords": [
     "cli",

package/rules/k8s/hasura_configmap/hasura_configmap.mdc

@@ -11,7 +11,7 @@ Rego-пакет: `k8s.hasura_configmap`
 | `HASURA_GRAPHQL_ENABLE_REMOTE_SCHEMA_PERMISSIONS` | `"true"` |
 | `HASURA_GRAPHQL_ENABLE_RELAY` | `"false"` |
 | `HASURA_GRAPHQL_ENABLE_TELEMETRY` | `"false"` |
-| `HASURA_GRAPHQL_ENABLED_LOG_TYPES` | `"startup,http-log"` (точно) |
+| `HASURA_GRAPHQL_ENABLED_LOG_TYPES` | `"startup,http-log"` (точно; base/dev; overlay має патчем замінити на `"startup"` — `http-log` лише для base/dev) |
 | `HASURA_GRAPHQL_ENABLED_APIS` | `"metadata,graphql,pgdump"` (base/dev; overlay має патчем замінити на `"metadata,graphql"`) |
 | `HASURA_GRAPHQL_DISABLE_EVENTING` | ключ обов'язковий, значення довільне (рекомендовано `"true"`) |
 

package/rules/k8s/manifests/main.mjs

@@ -4922,6 +4922,12 @@ const HASURA_OVERLAY_ENABLED_APIS = 'metadata,graphql'
 /** JSON-Pointer ключа `HASURA_GRAPHQL_ENABLED_APIS` у `data` ConfigMap (для JSON6902-патчів). */
 const HASURA_ENABLED_APIS_DATA_POINTER = '/data/HASURA_GRAPHQL_ENABLED_APIS'
 
+/** Очікуване `HASURA_GRAPHQL_ENABLED_LOG_TYPES` у non-base/dev overlay (без `http-log` — він лише для base/dev). */
+const HASURA_OVERLAY_ENABLED_LOG_TYPES = 'startup'
+
+/** JSON-Pointer ключа `HASURA_GRAPHQL_ENABLED_LOG_TYPES` у `data` ConfigMap (для JSON6902-патчів). */
+const HASURA_ENABLED_LOG_TYPES_DATA_POINTER = '/data/HASURA_GRAPHQL_ENABLED_LOG_TYPES'
+
 /**
  * Чи дерево kustomization (`resources` / `bases` / `components` / `crds`, рекурсивно) містить
  * **Hasura-Deployment** у шарі base (образ `hasura/graphql-engine`). Маркер того, що overlay успадковує
@@ -4965,18 +4971,19 @@ function firstValidYamlJsonFromPatchText(patchText) {
 }
 
 /**
- * Значення `data.HASURA_GRAPHQL_ENABLED_APIS` з JSON6902-патчу (масив операцій).
- * Повертає значення першої `add`/`replace`-операції на `/data/HASURA_GRAPHQL_ENABLED_APIS`.
+ * Значення `data.<dataKey>` з JSON6902-патчу (масив операцій).
+ * Повертає значення першої `add`/`replace`-операції на `/data/<dataKey>`.
  * @param {unknown[]} ops масив JSON6902-операцій
+ * @param {string} dataPointer JSON-Pointer ключа (`/data/<dataKey>`)
  * @returns {string | null} присвоєне значення (рядок) або null
  */
-function enabledApisValueFromJson6902(ops) {
+function hasuraDataKeyValueFromJson6902(ops, dataPointer) {
   for (const item of ops) {
     if (item === null || typeof item !== 'object' || Array.isArray(item)) continue
     const rec = /** @type {Record<string, unknown>} */ (item)
     const op = typeof rec.op === 'string' ? rec.op.trim().toLowerCase() : ''
     const path = typeof rec.path === 'string' ? normalizeJsonPatchPath(rec.path) : ''
-    if ((op === 'add' || op === 'replace') && path === HASURA_ENABLED_APIS_DATA_POINTER) {
+    if ((op === 'add' || op === 'replace') && path === dataPointer) {
       return typeof rec.value === 'string' ? rec.value : JSON.stringify(rec.value)
     }
   }
@@ -4984,42 +4991,58 @@ function enabledApisValueFromJson6902(ops) {
 }
 
 /**
- * Значення `data.HASURA_GRAPHQL_ENABLED_APIS` зі Strategic-Merge-патчу (об'єкт із `data`).
+ * Значення `data.<dataKey>` зі Strategic-Merge-патчу (об'єкт із `data`).
  * @param {object} parsed розпарсений об'єкт patch
+ * @param {string} dataKey ключ у `data` (наприклад `HASURA_GRAPHQL_ENABLED_APIS`)
  * @returns {string | null} присвоєне значення (рядок) або null
  */
-function enabledApisValueFromStrategicMerge(parsed) {
+function hasuraDataKeyValueFromStrategicMerge(parsed, dataKey) {
   const data = /** @type {Record<string, unknown>} */ (parsed).data
   if (data === null || typeof data !== 'object' || Array.isArray(data)) return null
   const d = /** @type {Record<string, unknown>} */ (data)
-  if (!Object.hasOwn(d, 'HASURA_GRAPHQL_ENABLED_APIS')) return null
-  const v = d.HASURA_GRAPHQL_ENABLED_APIS
+  if (!Object.hasOwn(d, dataKey)) return null
+  const v = d[dataKey]
   return typeof v === 'string' ? v : JSON.stringify(v)
 }
 
 /**
- * Значення, яке inline-`patch` присвоює `data.HASURA_GRAPHQL_ENABLED_APIS`. Підтримка двох форматів:
- * **JSON6902** (`op` add/replace на `/data/HASURA_GRAPHQL_ENABLED_APIS`) і **Strategic Merge**
- * (`data.HASURA_GRAPHQL_ENABLED_APIS`). Зовнішні patch-файли (`patches[].path`) не охоплені — Plan B trade-off.
+ * Значення, яке inline-`patch` присвоює `data.<dataKey>`. Підтримка двох форматів:
+ * **JSON6902** (`op` add/replace на `/data/<dataKey>`) і **Strategic Merge** (`data.<dataKey>`).
+ * Зовнішні patch-файли (`patches[].path`) не охоплені — Plan B trade-off.
  * @param {string} patchText вміст поля `patch`
+ * @param {string} dataKey ключ у `data`
+ * @param {string} dataPointer JSON-Pointer ключа (`/data/<dataKey>`)
  * @returns {string | null} присвоєне значення (рядок) або null, якщо patch не чіпає цей ключ
  */
-export function enabledApisValueFromPatchText(patchText) {
+function hasuraDataKeyValueFromPatchText(patchText, dataKey, dataPointer) {
   const t = typeof patchText === 'string' ? patchText.trim() : ''
   if (t === '') return null
   const parsed = firstValidYamlJsonFromPatchText(t)
-  if (Array.isArray(parsed)) return enabledApisValueFromJson6902(parsed)
+  if (Array.isArray(parsed)) return hasuraDataKeyValueFromJson6902(parsed, dataPointer)
   if (parsed === null || typeof parsed !== 'object') return null
-  return enabledApisValueFromStrategicMerge(parsed)
+  return hasuraDataKeyValueFromStrategicMerge(parsed, dataKey)
 }
 
 /**
- * Значення, яке `patches[]` kustomization присвоюють `data.HASURA_GRAPHQL_ENABLED_APIS` на цілі **ConfigMap**.
+ * Значення, яке inline-`patch` присвоює `data.HASURA_GRAPHQL_ENABLED_APIS`. Підтримка двох форматів:
+ * **JSON6902** (`op` add/replace на `/data/HASURA_GRAPHQL_ENABLED_APIS`) і **Strategic Merge**
+ * (`data.HASURA_GRAPHQL_ENABLED_APIS`). Зовнішні patch-файли (`patches[].path`) не охоплені — Plan B trade-off.
+ * @param {string} patchText вміст поля `patch`
+ * @returns {string | null} присвоєне значення (рядок) або null, якщо patch не чіпає цей ключ
+ */
+export function enabledApisValueFromPatchText(patchText) {
+  return hasuraDataKeyValueFromPatchText(patchText, 'HASURA_GRAPHQL_ENABLED_APIS', HASURA_ENABLED_APIS_DATA_POINTER)
+}
+
+/**
+ * Значення, яке `patches[]` kustomization присвоюють `data.<dataKey>` на цілі **ConfigMap**.
  * Повертає значення першого patch-а, що чіпає цей ключ, або null, якщо такого немає.
  * @param {Record<string, unknown>} kust об'єкт kustomization.yaml
+ * @param {string} dataKey ключ у `data`
+ * @param {string} dataPointer JSON-Pointer ключа (`/data/<dataKey>`)
  * @returns {string | null} присвоєне значення або null
  */
-export function hasuraEnabledApisOverrideValue(kust) {
+function hasuraDataKeyOverrideValue(kust, dataKey, dataPointer) {
   const patches = kust.patches
   if (!Array.isArray(patches)) return null
   for (const p of patches) {
@@ -5027,12 +5050,32 @@ export function hasuraEnabledApisOverrideValue(kust) {
     const pr = /** @type {Record<string, unknown>} */ (p)
     if (typeof pr.patch !== 'string') continue
     if (resolvePatchTargetKind(pr) !== 'ConfigMap') continue
-    const v = enabledApisValueFromPatchText(pr.patch)
+    const v = hasuraDataKeyValueFromPatchText(pr.patch, dataKey, dataPointer)
     if (v !== null) return v
   }
   return null
 }
 
+/**
+ * Значення, яке `patches[]` kustomization присвоюють `data.HASURA_GRAPHQL_ENABLED_APIS` на цілі **ConfigMap**.
+ * Повертає значення першого patch-а, що чіпає цей ключ, або null, якщо такого немає.
+ * @param {Record<string, unknown>} kust об'єкт kustomization.yaml
+ * @returns {string | null} присвоєне значення або null
+ */
+export function hasuraEnabledApisOverrideValue(kust) {
+  return hasuraDataKeyOverrideValue(kust, 'HASURA_GRAPHQL_ENABLED_APIS', HASURA_ENABLED_APIS_DATA_POINTER)
+}
+
+/**
+ * Значення, яке `patches[]` kustomization присвоюють `data.HASURA_GRAPHQL_ENABLED_LOG_TYPES` на цілі **ConfigMap**.
+ * Повертає значення першого patch-а, що чіпає цей ключ, або null, якщо такого немає.
+ * @param {Record<string, unknown>} kust об'єкт kustomization.yaml
+ * @returns {string | null} присвоєне значення або null
+ */
+export function hasuraEnabledLogTypesOverrideValue(kust) {
+  return hasuraDataKeyOverrideValue(kust, 'HASURA_GRAPHQL_ENABLED_LOG_TYPES', HASURA_ENABLED_LOG_TYPES_DATA_POINTER)
+}
+
 /**
  * Для кожного **non-base/dev** overlay `kustomization.yaml`, що успадковує Hasura-base (Deployment з
  * `hasura/graphql-engine`), вимагає у `patches[]` перевизначення **`data.HASURA_GRAPHQL_ENABLED_APIS`**
@@ -5070,6 +5113,43 @@ async function validateHasuraOverlayEnabledApisOverride(root, yamlFilesAbs, fail
   }
 }
 
+/**
+ * Для кожного **non-base/dev** overlay `kustomization.yaml`, що успадковує Hasura-base (Deployment з
+ * `hasura/graphql-engine`), вимагає у `patches[]` перевизначення **`data.HASURA_GRAPHQL_ENABLED_LOG_TYPES`**
+ * до **`"startup"`** (`http-log` лишається строго для base/dev — прод не пише per-request access-лог у
+ * Cloud Logging). `kind: Component` пропускається (env-неутральне джерело, не overlay).
+ * @param {string} root корінь репозиторію
+ * @param {string[]} yamlFilesAbs yaml під k8s
+ * @param {(msg: string) => void} fail callback при помилці
+ * @param {(msg: string) => void} passFn callback при успіху
+ */
+async function validateHasuraOverlayEnabledLogTypesOverride(root, yamlFilesAbs, fail, passFn) {
+  const rootNorm = resolve(root)
+  const kustFiles = yamlFilesAbs.filter(abs => basename(abs) === 'kustomization.yaml')
+  for (const kustAbs of kustFiles) {
+    const rel = (relative(rootNorm, kustAbs) || kustAbs).replaceAll('\\', '/')
+    const segment = k8sEnvSegmentFromRelPath(rel)
+    if (segment === null || segment === 'base' || segment === 'dev') continue
+    const kust = await readFirstYamlObject(kustAbs)
+    if (kust === null || kust.kind === 'Component') continue
+    if (!(await kustomizationTreeHasHasuraDeployment(kustAbs, rootNorm))) continue
+    const value = hasuraEnabledLogTypesOverrideValue(kust)
+    if (value === HASURA_OVERLAY_ENABLED_LOG_TYPES) {
+      passFn(
+        `${rel}: overlay '${segment}' перевизначає HASURA_GRAPHQL_ENABLED_LOG_TYPES="${HASURA_OVERLAY_ENABLED_LOG_TYPES}" (k8s.mdc)`
+      )
+    } else if (value === null) {
+      fail(
+        `${rel}: overlay '${segment}' має у patches[] перевизначати data.HASURA_GRAPHQL_ENABLED_LOG_TYPES до "${HASURA_OVERLAY_ENABLED_LOG_TYPES}" (http-log лише для base/dev) (k8s.mdc)`
+      )
+    } else {
+      fail(
+        `${rel}: overlay '${segment}' patch data.HASURA_GRAPHQL_ENABLED_LOG_TYPES має бути "${HASURA_OVERLAY_ENABLED_LOG_TYPES}" (зараз: ${JSON.stringify(value)}) (k8s.mdc)`
+      )
+    }
+  }
+}
+
 /**
  * Шукає HPA за `scaleTargetRef.name` серед документів.
  * @param {Record<string, unknown>[]} hpaDocs масив HPA-документів
@@ -6658,6 +6738,8 @@ export async function lint(ctx) {
 
   await validateHasuraOverlayEnabledApisOverride(root, yamlFiles, fail, pass)
 
+  await validateHasuraOverlayEnabledLogTypesOverride(root, yamlFiles, fail, pass)
+
   return reporter.result()
 }
 

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

@@ -3,7 +3,8 @@ type: JS Module
 title: main.mjs
 resource: npm/rules/text/run-v8r/main.mjs
 docgen:
-  crc: 804dce1c
+  crc: 5c8aab7b
+  model: manual
 ---
 
 ## Огляд
@@ -20,18 +21,20 @@ docgen:
 - `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.
+- `runV8rWithGlobs(globs?)` — послідовно запускає `v8r` для кожного glob-у з `V8R_CONFIG_FILE`, вказаним на резольвнутий конфіг; повертає `{ code, detail }` (не голий код): при `code` 0/98 вивід приховано, `detail` порожній; інакше `detail` друкується й повертається код першого невдалого прогону.
+- `runV8rWithFiles(files)` — delta-режим: один запуск `v8r` по конкретних існуючих шляхах (код 98 неможливий), порожній список — одразу `{ code: 0, detail: '' }`.
+- `extractFailureLines(combinedText)` — фільтрує `ℹ`-шум і bunx install-вивід з об'єднаного `stdout+stderr` одного запуску `v8r`, лишаючи предметну деталь (`✖ …`-заголовки, ajv-причини). Обидва потоки об'єднуються навмисно: `v8r` непослідовно розкидає деталь між ними залежно від типу помилки (schema violation — причина в stdout, заголовок у stderr; "не знайдено схему" — усе в stderr).
 - `warnAboutRemoteSchemaFallback(stderrText)` — парсить stderr `v8r` і на кожен файл, чию схему знайдено мережевим fallback-ом (schemastore, не customCatalog), друкує в stdout пораду додати схему в каталог.
 - `stripBunNodeShimDirs(pathValue)` — прибирає з PATH shim-теки `bun-node-*`, які `bun run --bun` додає з підміненим `node`: дочірній `v8r` (node-shebang) інакше виконувався б під bun і падав на непідтримуваному `node:sea`. Дочірній процес `v8r` завжди отримує очищений PATH.
-- `lint(ctx)` — detector `text/run-v8r`: `ctx.files` → delta по відфільтрованих розширеннях, без `ctx.files` → full за `DEFAULT_V8R_GLOBS`.
+- `lint(ctx)` — detector `text/run-v8r`: `ctx.files` → delta по відфільтрованих розширеннях, без `ctx.files` → full за `DEFAULT_V8R_GLOBS`. Порушення несе `detail` (якщо є) у тексті `fail()`-повідомлення — без нього LLM fix-worker бачив лише "щось не пройшло" й незмінно провалював усі rung-и драбини (не мав інформації, що саме виправляти).
 
 ## Публічний API
 
 - `DEFAULT_V8R_GLOBS`, `V8R_CATALOG_PATH`, `RESOLVED_V8R_CONFIG_PATH`, `V8R_CACHE_TTL_SECONDS` — константи.
 - `resolveCustomCatalogSchemas()` — обчислені схеми customCatalog.
 - `writeResolvedV8rConfig()` — матеріалізація тимчасового конфігу, повертає його шлях.
-- `runV8rWithGlobs(globs?)`, `runV8rWithFiles(files)` — точки входу перевірки (full/delta).
+- `runV8rWithGlobs(globs?)`, `runV8rWithFiles(files)` — точки входу перевірки (full/delta), повертають `{ code, detail }`.
+- `extractFailureLines(combinedText)` — фільтр noise-рядків для деталі провалу.
 - `warnAboutRemoteSchemaFallback(stderrText)` — попередження про мережевий fallback схем.
 - `stripBunNodeShimDirs(pathValue)` — PATH без shim-тек `bun-node-*` (для дочірнього v8r).
 - `lint(ctx)` — інтеграція в lint-пайплайн.

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

@@ -114,17 +114,28 @@ export function writeResolvedV8rConfig() {
 
 const PROCESSING_LINE_RE = /^ℹ Processing (.+)$/u
 const FOUND_REMOTE_SCHEMA_RE = /^ℹ Found schema in (https?:\/\/\S+)/u
-const FAILURE_LINE_RE = /^✖ .+$/mu
+const NOISE_LINE_RE = /^(?:ℹ .*|Resolving dependencies|Resolved, downloaded and extracted.*|Saved lockfile)$/u
 
 /**
- * Витягує лише рядки `✖ …` (конкретні помилки валідації) з raw stdout v8r — без `ℹ`-шуму
- * (Pre-warming the cache, Processing <file>, Found schema in …) і без `✔ … is valid` по
- * пройдених файлах. Використовується для non-verbose підсумку при невдалому прогоні.
- * @param {string} stdoutText захоплений stdout одного запуску v8r
- * @returns {string} рядки `✖ …`, з'єднані `\n` (порожній рядок, якщо збігів нема)
+ * Прибирає v8r/bunx noise-рядки (весь `ℹ`-статус: Loaded config file, Patterns and relative
+ * paths, Pre-warming the cache, Processing <file>, Found schema in …, Validating …; і службовий
+ * вивід bunx-встановлення Resolving/Resolved/Saved lockfile) з об'єднаного stdout+stderr одного
+ * запуску —
+ * лишає предметну деталь (`✖ …`-заголовки й ajv-причини на кшталт "must NOT have additional
+ * properties…"). Обидва потоки об'єднуються НАВМИСНО: v8r непослідовно розкидає ці рядки між
+ * stdout/stderr залежно від типу помилки — при порушенні схеми ajv-причина йде у stdout, а
+ * `✖ … is invalid`-заголовок у stderr; при "не знайдено схему" все йде у stderr, stdout
+ * порожній. Фільтр лише за stdout (як раніше) на другому випадку повертав би зовсім порожню
+ * деталь — і LLM fix-worker (як і non-verbose CLI-підсумок) не бачив би жодної причини провалу.
+ * @param {string} combinedText stdout + '\n' + stderr одного запуску v8r
+ * @returns {string} відфільтровані непорожні рядки, join('\n') (порожній рядок, якщо деталі нема)
  */
-export function extractFailureLines(stdoutText) {
-  return (stdoutText.match(FAILURE_LINE_RE) ?? []).join('\n')
+export function extractFailureLines(combinedText) {
+  return combinedText
+    .split('\n')
+    .map(line => line.trim())
+    .filter(line => line.length > 0 && !NOISE_LINE_RE.test(line))
+    .join('\n')
 }
 
 /**
@@ -168,11 +179,16 @@ export function stripBunNodeShimDirs(pathValue) {
 
 /**
  * Один виклик `bun x v8r <targets...>` з підготовленим `customCatalog`-конфігом.
+ * `detail` (рядки `✖ …`) обчислюється завжди, незалежно від `verbose` — потрібен викликачу
+ * (`lint()`) для вбудовування у violation-повідомлення, яке бачить LLM fix-worker: без нього
+ * fix-ladder отримує лише "щось не пройшло" й не має шансів вгадати, що саме (спостережено —
+ * усі 4 rung-и незмінно падають у timeout на v8r-порушеннях).
  * @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 — трактує викликач)
+ * @returns {{ exitError: true } | { exitError: false, code: number, detail: string }} помилка
+ *   spawn або код v8r (0/98 — трактує викликач) + деталь `✖ …`-рядків
  */
 function runOneV8rInvocation(targets, configPath, verbose = false) {
   const bunPath = resolveCmd('bun') ?? process.execPath
@@ -192,16 +208,17 @@ function runOneV8rInvocation(targets, configPath, verbose = false) {
   warnAboutRemoteSchemaFallback(result.stderr ?? '')
 
   const exitCode = result.status ?? 1
+  let detail = ''
   if (exitCode !== 0 && exitCode !== 98) {
+    detail = extractFailureLines(`${result.stdout ?? ''}\n${result.stderr ?? ''}`)
     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`)
+    } else if (detail.length) {
+      process.stdout.write(`${detail}\n`)
     }
   }
-  return { exitError: false, code: exitCode }
+  return { exitError: false, code: exitCode, detail }
 }
 
 /**
@@ -210,24 +227,25 @@ function runOneV8rInvocation(targets, configPath, verbose = false) {
  * glob не знаходить файлів, і тоді решта розширень не перевіряються в тому ж виклику.
  * @param {string[]} [globs] патерни; за замовчуванням DEFAULT_V8R_GLOBS
  * @param {boolean} [verbose] друкувати повний raw вивід v8r при помилці (див. runOneV8rInvocation)
- * @returns {number} 0 — OK, 1 — помилка spawn, 2 — немає каталогу схем, інше — код v8r
+ * @returns {{ code: number, detail: string }} `code`: 0 — OK, 1 — помилка spawn, 2 — немає
+ *   каталогу схем, інше — код v8r; `detail` — рядки `✖ …` (порожньо, якщо `code` не про валідацію)
  */
 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
+    return { code: 2, detail: '' }
   }
 
   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
+    if (r.exitError) return { code: 1, detail: '' }
+    if (r.code !== 0 && r.code !== 98) return { code: r.code, detail: r.detail }
   }
-  return 0
+  return { code: 0, detail: '' }
 }
 
 /**
@@ -235,21 +253,33 @@ export function runV8rWithGlobs(globs = DEFAULT_V8R_GLOBS, verbose = false) {
  * бо кожен переданий шлях уже існує (не glob), тож код 98 "порожній glob" тут не виникає.
  * @param {string[]} files абсолютні або відносні до cwd v8r-процесу шляхи файлів
  * @param {boolean} [verbose] друкувати повний raw вивід v8r при помилці (див. runOneV8rInvocation)
- * @returns {number} 0 — OK, 1 — помилка spawn, 2 — немає каталогу схем, інше — код v8r
+ * @returns {{ code: number, detail: string }} `code`: 0 — OK, 1 — помилка spawn, 2 — немає
+ *   каталогу схем, інше — код v8r; `detail` — рядки `✖ …` (порожньо, якщо `code` не про валідацію)
  */
 export function runV8rWithFiles(files, verbose = false) {
-  if (files.length === 0) return 0
+  if (files.length === 0) return { code: 0, detail: '' }
   if (!existsSync(V8R_CATALOG_PATH)) {
     process.stderr.write(
       `run-v8r: не знайдено каталог схем за шляхом ${V8R_CATALOG_PATH} (очікується npm/schemas/v8r-catalog.json у пакеті)\n`
     )
-    return 2
+    return { code: 2, detail: '' }
   }
 
   const configPath = writeResolvedV8rConfig()
   const r = runOneV8rInvocation(files, configPath, verbose)
-  if (r.exitError) return 1
-  return r.code === 98 ? 0 : r.code
+  if (r.exitError) return { code: 1, detail: '' }
+  return { code: r.code === 98 ? 0 : r.code, detail: r.detail }
+}
+
+/**
+ * Будує violation-повідомлення з опційною деталлю `✖ …`-рядків v8r — без неї LLM fix-worker
+ * бачить лише "щось не пройшло" й не має інформації, який файл/поле саме порушує схему.
+ * @param {string} detail рядки `✖ …` з `runV8rWithGlobs`/`runV8rWithFiles` (може бути порожнім)
+ * @returns {string} повне повідомлення для `fail()`
+ */
+function v8rFailMessage(detail) {
+  const base = 'v8r schema-валідація json/yaml/toml не пройшла (text.mdc)'
+  return detail ? `${base}:\n${detail}` : base
 }
 
 /**
@@ -264,19 +294,19 @@ export function lint(ctx) {
   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')
+    const { code, detail } = runV8rWithGlobs(DEFAULT_V8R_GLOBS, verbose)
+    if (code !== 0) fail(v8rFailMessage(detail), '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')
+  const { code, detail } = runV8rWithFiles(files, verbose)
+  if (code !== 0) fail(v8rFailMessage(detail), '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)
+  process.exitCode = runV8rWithGlobs(globs).code
 }