@7n/rules 1.0.0

package/scripts/lib/read-n-rules-config-lite.mjs

@@ -0,0 +1,63 @@
+/**
+ * Light read-only `.n-rules.json` reader (fallback — legacy `.n-cursor.json`) для standalone `check.mjs` invocation.
+ *
+ * НЕ робить auto-rules detection, merge, schema sync — це справа повного `readConfig` у CLI.
+ * Тут лише: прочитати файл (якщо є), повернути `{ rules: string[], disableRules: string[] }`.
+ *
+ * Спостереження whitelist:
+ *   - якщо `.n-rules.json` НЕМАЄ → правило вважається enabled (поведінка "open by default"),
+ *     щоб `bun rules/<id>/check.mjs` з будь-якої тимчасової директорії працювало для debug.
+ *   - якщо файл є з `rules:[…]`, але правила там немає → правило не enabled.
+ *   - якщо правило в `disable-rules` → не enabled, навіть якщо у `rules:[…]`.
+ */
+import { existsSync } from 'node:fs'
+import { readFile } from 'node:fs/promises'
+import { join } from 'node:path'
+
+const CONFIG_FILE = '.n-rules.json'
+const LEGACY_CONFIG_FILE = '.n-cursor.json'
+
+/**
+ * @typedef {object} LiteConfig
+ * @property {boolean} exists чи існує .n-rules.json (або legacy .n-rules.json) у поточному каталозі
+ * @property {string[]} rules id правил з whitelist (порожній якщо файл відсутній)
+ * @property {string[]} disableRules id правил, явно вимкнених у `disable-rules`
+ */
+
+/**
+ * @param {string} [cwd] корінь, у якому шукати .n-rules.json (default — `process.cwd()`)
+ * @returns {Promise<LiteConfig>} стан конфігу
+ */
+export async function readNRulesConfigLite(cwd = process.cwd()) {
+  let configPath = join(cwd, CONFIG_FILE)
+  if (!existsSync(configPath)) {
+    configPath = join(cwd, LEGACY_CONFIG_FILE)
+  }
+  if (!existsSync(configPath)) {
+    return { exists: false, rules: [], disableRules: [] }
+  }
+  const raw = await readFile(configPath, 'utf8')
+  /** @type {{ rules?: unknown, ['disable-rules']?: unknown }} */
+  const parsed = JSON.parse(raw)
+  const rules = Array.isArray(parsed.rules) ? parsed.rules.filter(r => typeof r === 'string') : []
+  const disableRules = Array.isArray(parsed['disable-rules'])
+    ? parsed['disable-rules'].filter(r => typeof r === 'string')
+    : []
+  return { exists: true, rules, disableRules }
+}
+
+/**
+ * Чи активне правило згідно з конфігом.
+ *   - файл відсутній → true (open by default для debug);
+ *   - правило явно в `disable-rules` → false;
+ *   - правило у `rules` → true;
+ *   - інакше → false.
+ * @param {LiteConfig} config розпарсений lite-конфіг
+ * @param {string} ruleId id правила (= basename каталогу)
+ * @returns {boolean} чи запускати правило
+ */
+export function isRuleEnabled(config, ruleId) {
+  if (!config.exists) return true
+  if (config.disableRules.includes(ruleId)) return false
+  return config.rules.includes(ruleId)
+}

package/scripts/lib/resolve-target-files.mjs

@@ -0,0 +1,103 @@
+/**
+ * Резолвер списку файлів для одного `policy/<name>/target.json` у новій структурі правил.
+ *
+ * Дві форми у `target.json:files`:
+ *   - `{ "single": "<rel>" }` — конкретний відносний шлях. Якщо `existsSync(root/single)` → `[single]`;
+ *     інакше `[]` (caller сам вирішує fail vs silent skip за `required`).
+ *   - `{ "walkGlob": <glob | glob[]> }` — `ignore` проти posix-відносних шляхів, отриманих обходом
+ *     `walkDir` від `root` із загальними skip-ами та `.n-rules.json:ignore`. Обхід кешований у
+ *     `walkCache` (Map ключ — підпис ignorePaths) — повторні таргети з тим самим набором ignore
+ *     перевикористовують список без нового readdir.
+ *
+ * Path-traversal у `single` — кидаємо помилку при resolve. Реалізує інваріант контракту: полісі
+ * читають лише файли в репо.
+ */
+import { existsSync } from 'node:fs'
+import { isAbsolute, join, normalize, relative, sep } from 'node:path'
+
+import ignore from 'ignore'
+
+import { loadCursorIgnorePaths } from './load-cursor-config.mjs'
+import { walkDir } from '../utils/walkDir.mjs'
+
+/** Узгоджений regex для path-traversal: `..` як сегмент або абсолютний шлях. */
+const PARENT_SEGMENT_RE = /(^|[\\/])\.\.([\\/]|$)/u
+
+/**
+ * Перевіряє, що `single`-шлях у `target.json:files` лежить у межах репозиторію.
+ * Кидає помилку, якщо шлях абсолютний або містить сегмент `..`.
+ * @param {string} singlePath значення `files.single`
+ * @returns {void}
+ */
+function assertSafeSinglePath(singlePath) {
+  if (isAbsolute(singlePath)) {
+    throw new Error(`target.json: files.single має бути відносним шляхом (отримано: ${singlePath})`)
+  }
+  if (PARENT_SEGMENT_RE.test(singlePath)) {
+    throw new Error(`target.json: files.single не може містити '..' (отримано: ${singlePath})`)
+  }
+}
+
+/**
+ * Збирає всі файли (posix-відносні шляхи від `root`) одним обходом дерева.
+ * Скіпи: загальні з `walkDir` + `.n-rules.json:ignore`.
+ * @param {string} root абсолютний корінь репозиторію
+ * @param {string[]} ignorePaths абсолютні posix-шляхи виключених каталогів
+ * @returns {Promise<string[]>} відсортовані posix-відносні шляхи
+ */
+async function walkAllRelative(root, ignorePaths) {
+  /** @type {string[]} */
+  const out = []
+  await walkDir(
+    root,
+    abs => {
+      const rel = relative(root, abs).split(sep).join('/')
+      if (rel.length > 0) out.push(rel)
+    },
+    ignorePaths
+  )
+  return out.toSorted((a, b) => a.localeCompare(b))
+}
+
+/**
+ * Витягує (або обчислює і кешує) список усіх файлів у дереві для заданого набору ignore-шляхів.
+ * Кеш — мапа `signature → Promise<string[]>`, тож паралельні виклики одного й того ж набору
+ * чекають один обхід.
+ * @param {string} root абсолютний корінь репозиторію
+ * @param {string[]} ignorePaths абсолютні posix-шляхи виключених каталогів
+ * @param {Map<string, Promise<string[]>>} walkCache мутабельний кеш від caller-а
+ * @returns {Promise<string[]>} відсортовані posix-відносні шляхи
+ */
+function getAllFilesCached(root, ignorePaths, walkCache) {
+  const signature = `${root}|${ignorePaths.join('|')}`
+  let p = walkCache.get(signature)
+  if (!p) {
+    p = walkAllRelative(root, ignorePaths)
+    walkCache.set(signature, p)
+  }
+  return p
+}
+
+/**
+ * Резолвить список файлів для одного `target.json:files`.
+ * @param {object} filesSpec поле `files` з `target.json` (вже після schema-валідації)
+ * @param {string} root абсолютний корінь репозиторію
+ * @param {Map<string, Promise<string[]>>} walkCache кеш обходів дерева (cross-target у межах одного check-прогону)
+ * @returns {Promise<string[]>} абсолютні шляхи знайдених файлів (порожній — нічого не знайдено)
+ */
+export async function resolveTargetFiles(filesSpec, root, walkCache) {
+  if (typeof filesSpec?.single === 'string') {
+    assertSafeSinglePath(filesSpec.single)
+    const normalized = normalize(filesSpec.single).split(sep).join('/')
+    const abs = join(root, normalized)
+    return existsSync(abs) ? [abs] : []
+  }
+  if (filesSpec?.walkGlob !== undefined) {
+    const ignorePaths = await loadCursorIgnorePaths(root)
+    const all = await getAllFilesCached(root, ignorePaths, walkCache)
+    const globs = Array.isArray(filesSpec.walkGlob) ? filesSpec.walkGlob : [filesSpec.walkGlob]
+    const ig = ignore().add(globs)
+    return all.filter(rel => ig.ignores(rel)).map(rel => join(root, rel))
+  }
+  throw new Error(`target.json: files має містити single або walkGlob (отримано: ${JSON.stringify(filesSpec)})`)
+}

package/scripts/lib/root-notice.mjs

@@ -0,0 +1,67 @@
+/**
+ * Вшивання root-guard preflight у синкнутий `SKILL.md` для скілів, що **мутують
+ * проєкт у поточному каталозі**, але виконуються **in-place** (без worktree-
+ * ізоляції) — `meta.json` → `requireRoot: true` і `worktree: false`.
+ *
+ * Worktree-скіли (`worktree: true`) свій root-assert уже мають у worktree-блоці
+ * (`worktree-notice.mjs`): корінь worktree = його toplevel. Цей модуль — для
+ * не-worktree-кейсу (напр. `n-taze`, що мутує `package.json` безпосередньо
+ * й має стартувати з кореня монорепо).
+ *
+ * Блок — інструкція агенту, що читає `SKILL.md`; вставляється між стабільними
+ * маркерами, ре-синк ідемпотентний: наявний блок замінюється, при `false` —
+ * видаляється. Програмний аналог для CLI-команд — `assertCwdIsProjectRoot`.
+ */
+
+/** Маркер початку root-блоку. */
+export const ROOT_START = '<!-- n-rules:root:start -->'
+/** Маркер кінця root-блоку. */
+export const ROOT_END = '<!-- n-rules:root:end -->'
+
+/** Наявний блок разом із сусідніми порожніми рядками (для чистого видалення). */
+// Матчить і legacy `n-rules:`-маркери, щоб ре-синк замінював блоки, згенеровані до перейменування пакету
+const BLOCK_RE = /\n{0,8}<!-- n-(?:cursor|rules):root:start -->[\s\S]*?<!-- n-(?:cursor|rules):root:end -->\n{0,8}/u
+
+/** Закриття YAML-frontmatter на початку файла. */
+const FRONTMATTER_RE = /^(---\n[\s\S]*?\n---\n)/u
+
+/** Тіло root-guard інструкції. */
+const NOTICE_BODY = `> [!IMPORTANT]
+> **Root-only skill.** Скіл мутує проєкт у поточному каталозі й має запускатися **з кореня репозиторію**.
+
+**Крок 0 — preflight (обовʼязковий, перед будь-якими іншими діями).**
+
+\`\`\`bash
+pwd
+git rev-parse --show-toplevel
+\`\`\`
+
+Якщо \`pwd\` **не** збігається з виводом \`git rev-parse --show-toplevel\` — ти в **піддиректорії**. **STOP**: перейди в корінь (\`cd <toplevel>\`, literal-шлях із виводу) і лише тоді виконуй наступні кроки скіла. Поза git-репо (команда без виводу) — продовжуй (корінь визначити неможливо).`
+
+/** Канонічний блок root-інструкції (з маркерами). */
+const BLOCK = `${ROOT_START}\n${NOTICE_BODY}\n${ROOT_END}`
+
+const LEADING_NEWLINES_RE = /^\n+/u
+
+/**
+ * Вставляє / оновлює / видаляє root-guard блок у вмісті `SKILL.md`.
+ * @param {string} content вміст `SKILL.md`
+ * @param {boolean} enabled чи має бути блок (`requireRoot && !worktree`)
+ * @returns {string} оновлений вміст (ідемпотентно)
+ */
+export function injectRootNotice(content, enabled) {
+  const hadBlock = content.includes(ROOT_START)
+  const withoutBlock = content.replace(BLOCK_RE, '\n\n')
+
+  if (!enabled) {
+    return hadBlock ? withoutBlock : content
+  }
+
+  const fm = withoutBlock.match(FRONTMATTER_RE)
+  if (fm) {
+    const head = fm[1]
+    const rest = withoutBlock.slice(head.length).replace(LEADING_NEWLINES_RE, '')
+    return `${head}\n${BLOCK}\n\n${rest}`
+  }
+  return `${BLOCK}\n\n${withoutBlock.replace(LEADING_NEWLINES_RE, '')}`
+}

package/scripts/lib/rule-meta-helpers.mjs

@@ -0,0 +1,103 @@
+/**
+ * Чисті хелпери конфігу/репо для автодетекту правил: id-міграції, нормалізація
+ * списків, repository URL, monorepo-детект.
+ *
+ * Винесені з `auto-rules.mjs`, щоб `rule-predicates.mjs` міг використати
+ * `getRepositoryUrl` без циклу імпортів. `auto-rules.mjs` пізніше ре-експортує їх звідси.
+ */
+
+/**
+ * Карта міграції застарілих rule-id у `.n-rules.json` на актуальні.
+ * Застосовується автоматично при читанні конфігу (як для `rules`, так і для `disable-rules`).
+ * Приклад: `image` → `image-compress` + `image-avif` (правило розщеплене у 1.8.197).
+ */
+export const RULE_MIGRATIONS = Object.freeze(
+  /** @type {Record<string, readonly string[]>} */ ({
+    image: Object.freeze(['image-compress', 'image-avif'])
+  })
+)
+
+/**
+ * Розгортає застарілі rule-id у списку згідно з `RULE_MIGRATIONS`. Зберігає порядок,
+ * дедуплікує. Чистий хелпер: не мутує вхід, не логує.
+ * @param {string[]} ids нормалізований список id (як з `normalizeIdList`)
+ * @returns {string[]} список з legacy-id, заміненими на нові; решта без змін
+ */
+export function migrateRuleIds(ids) {
+  /** @type {string[]} */
+  const out = []
+  for (const id of ids) {
+    const replacement = Object.hasOwn(RULE_MIGRATIONS, id) ? RULE_MIGRATIONS[id] : [id]
+    for (const newId of replacement) {
+      if (!out.includes(newId)) out.push(newId)
+    }
+  }
+  return out
+}
+
+/**
+ * Повертає лише ті legacy rule-id зі списку, для яких є запис у `RULE_MIGRATIONS`.
+ * Використовується для людинозрозумілого логування міграції при синхронізації CLI.
+ * @param {string[]} ids нормалізований список id
+ * @returns {string[]} legacy id, які потребуватимуть заміни у `migrateRuleIds`
+ */
+export function detectLegacyRuleIds(ids) {
+  return ids.filter(id => Object.hasOwn(RULE_MIGRATIONS, id))
+}
+
+/**
+ * Нормалізує список ідентифікаторів (trim + lowercase + унікальність збереженням порядку).
+ * @param {unknown} value вихідне значення з `.n-rules.json`
+ * @returns {string[]} масив id у нормалізованому вигляді
+ */
+export function normalizeIdList(value) {
+  if (!Array.isArray(value)) {
+    return []
+  }
+  const out = []
+  for (const item of value) {
+    const normalized = String(item).trim().toLowerCase()
+    if (normalized && !out.includes(normalized)) {
+      out.push(normalized)
+    }
+  }
+  return out
+}
+
+/**
+ * Повертає URL репозиторію з package.json (`repository` може бути рядком або обʼєктом).
+ * @param {unknown} repository значення `packageJson.repository`
+ * @returns {string | null} URL або null
+ */
+export function getRepositoryUrl(repository) {
+  if (typeof repository === 'string') {
+    return repository
+  }
+  if (repository && typeof repository === 'object' && !Array.isArray(repository)) {
+    const url = /** @type {Record<string, unknown>} */ (repository).url
+    if (typeof url === 'string') {
+      return url
+    }
+  }
+  return null
+}
+
+/**
+ * Чи package.json виглядає як монорепо (поле `workspaces`).
+ * @param {unknown} packageJson кореневий package.json як JS-обʼєкт
+ * @returns {boolean} true, якщо оголошено workspaces
+ */
+export function isMonorepoPackage(packageJson) {
+  if (packageJson === null || typeof packageJson !== 'object' || Array.isArray(packageJson)) {
+    return false
+  }
+  const workspaces = /** @type {Record<string, unknown>} */ (packageJson).workspaces
+  if (Array.isArray(workspaces)) {
+    return workspaces.length > 0
+  }
+  if (workspaces && typeof workspaces === 'object' && !Array.isArray(workspaces)) {
+    const packages = /** @type {Record<string, unknown>} */ (workspaces).packages
+    return Array.isArray(packages) && packages.length > 0
+  }
+  return false
+}

package/scripts/lib/rule-meta.mjs

@@ -0,0 +1,66 @@
+/**
+ * Парсер метаданих правила з `npm/rules/<id>/main.json` (data-driven автодетект).
+ *
+ * `main.json.auto` має один із чотирьох видів:
+ *  - `"завжди"`                       → always-on;
+ *  - `["rule", …]`                    → активується, коли всі правила-залежності виявлені;
+ *  - `{ "glob": "<pat>" | [<pat>] }`  → наявність файлів/каталогів за glob (OR);
+ *  - `{ "predicate": "<name>", "arg"? }` → незводимий предикат із реєстру `rule-predicates.mjs`.
+ *
+ * Поля `worktree` правило НЕ має (це скілова вісь). Дзеркало `skill-meta.mjs`.
+ */
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+/** Літерал безумовної активації (українською, як у скілах). */
+export const RULE_ALWAYS = 'завжди'
+
+/**
+ * @typedef {{ always: true } | { rules: string[] } | { glob: string[] } | { predicate: string, arg: unknown }} RuleAutoSpec
+ */
+
+/**
+ * Нормалізує значення `main.json.auto` у дискриміновану форму.
+ * @param {unknown} value значення поля `auto`
+ * @returns {RuleAutoSpec | null} `null` — формат не розпізнано (= opt-in)
+ */
+export function parseRuleAutoSpec(value) {
+  if (value === RULE_ALWAYS) return { always: true }
+
+  if (Array.isArray(value)) {
+    const rules = value.map(s => String(s).trim()).filter(s => s.length > 0)
+    return rules.length > 0 ? { rules } : null
+  }
+
+  if (value !== null && typeof value === 'object') {
+    const obj = /** @type {Record<string, unknown>} */ (value)
+    if ('glob' in obj) {
+      const raw = obj.glob
+      const globs = (Array.isArray(raw) ? raw : [raw]).filter(g => typeof g === 'string' && g.length > 0)
+      return globs.length > 0 ? { glob: /** @type {string[]} */ (globs) } : null
+    }
+    if ('predicate' in obj) {
+      return typeof obj.predicate === 'string' && obj.predicate.length > 0
+        ? { predicate: obj.predicate, arg: obj.arg }
+        : null
+    }
+  }
+  return null
+}
+
+/**
+ * Читає й парсить `main.json` одного правила.
+ * @param {string} ruleDir абсолютний шлях до каталогу правила
+ * @returns {Record<string, unknown> | null} обʼєкт або `null` (немає файлу / невалідний JSON / не-обʼєкт)
+ */
+export function readRuleMetaRaw(ruleDir) {
+  const metaPath = join(ruleDir, 'main.json')
+  if (!existsSync(metaPath)) return null
+  try {
+    const parsed = JSON.parse(readFileSync(metaPath, 'utf8'))
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) return null
+    return /** @type {Record<string, unknown>} */ (parsed)
+  } catch {
+    return null
+  }
+}

package/scripts/lib/rule-predicates.mjs

@@ -0,0 +1,114 @@
+/**
+ * Реєстр незводимих до даних предикатів автодетекту правил.
+ *
+ * Прості умови (наявність файлів) живуть як `glob` у `meta.json`; ці предикати —
+ * для умов, що вимагають парсингу залежностей, сканування вмісту source чи URL repo.
+ * Декларація «який предикат + аргумент» — у `meta.json.auto.predicate`; тут — реалізація.
+ *
+ * Сигнатури неоднорідні (одні беруть `facts`, інші — `cwd`/`packageJson`), бо предикати
+ * читають різні джерела; виклик диспетчиться в `auto-rules.mjs` за іменем предиката.
+ */
+import { readFile } from 'node:fs/promises'
+import { join } from 'node:path'
+
+import { findAllPackageJsonPaths } from '../utils/find-package-json-paths.mjs'
+import { getRepositoryUrl } from './rule-meta-helpers.mjs'
+
+/**
+ * Чи package.json дерева містить будь-який із зазначених пакетів у dependencies.
+ * Обхід — через `findAllPackageJsonPaths` (на `walkDir`/`globby`), тож **поважає `.gitignore`**
+ * і не зчитує package.json з ігнорованих каталогів (build-артефакти, vendored-копії).
+ * @param {string} root корінь репо
+ * @param {string[]} keys імена пакетів
+ * @returns {Promise<boolean>} true, якщо знайдено хоч один
+ */
+async function anyDepInTree(root, keys) {
+  const wanted = new Set(keys)
+  for (const abs of await findAllPackageJsonPaths(root, [])) {
+    try {
+      const deps = JSON.parse(await readFile(abs, 'utf8'))?.dependencies
+      if (deps && typeof deps === 'object' && !Array.isArray(deps)) {
+        for (const k of wanted) if (Object.hasOwn(deps, k)) return true
+      }
+    } catch {
+      /* ігноруємо пошкоджені package.json */
+    }
+  }
+  return false
+}
+
+/**
+ * Чи існує вкладений (не кореневий) package.json без `vite` у devDependencies.
+ * Обхід — `findAllPackageJsonPaths` (gitignore-aware), як у `anyDepInTree`.
+ * @param {string} root корінь репо
+ * @returns {Promise<boolean>} true, якщо знайдено
+ */
+async function nestedWithoutVite(root) {
+  const rootPkg = join(root, 'package.json')
+  for (const abs of await findAllPackageJsonPaths(root, [])) {
+    if (abs === rootPkg) continue
+    try {
+      const dev = JSON.parse(await readFile(abs, 'utf8'))?.devDependencies
+      const hasVite = dev && typeof dev === 'object' && !Array.isArray(dev) && Object.hasOwn(dev, 'vite')
+      if (!hasVite) return true
+    } catch {
+      /* пошкоджений package.json не вважаємо vite-проєктом */
+    }
+  }
+  return false
+}
+
+/** Реєстр предикатів: імʼя → реалізація. Виклик за `meta.json.auto.predicate`. */
+export const RULE_PREDICATES = {
+  /**
+   * @param {unknown} packageJson кореневий package.json
+   * @param {string} arg підрядок-маркер URL
+   * @returns {boolean} true, якщо repository.url містить маркер
+   */
+  repoUrlMarker(packageJson, arg) {
+    const url = getRepositoryUrl(
+      packageJson && typeof packageJson === 'object' && !Array.isArray(packageJson)
+        ? /** @type {Record<string, unknown>} */ (packageJson).repository
+        : null
+    )
+    return typeof url === 'string' && url.toLowerCase().includes(String(arg).toLowerCase())
+  },
+  /**
+   * @param {string} cwd корінь репо
+   * @param {string[]} arg імена пакетів
+   * @returns {Promise<boolean>} true, якщо будь-який пакет у dependencies дерева
+   */
+  depInAnyPackageJson(cwd, arg) {
+    return anyDepInTree(cwd, Array.isArray(arg) ? arg : [])
+  },
+  /**
+   * @param {{ hasGqlTaggedTemplates: boolean }} facts факти
+   * @returns {boolean} true, якщо є gql-літерал
+   */
+  gqlTaggedTemplate(facts) {
+    return facts.hasGqlTaggedTemplates === true
+  },
+  /**
+   * @param {{ hasHasuraConfig: boolean }} facts факти
+   * @returns {boolean} true, якщо config.yaml із маркером
+   */
+  hasuraConfigMarker(facts) {
+    return facts.hasHasuraConfig === true
+  },
+  /**
+   * @param {string} cwd корінь репо
+   * @param {{ hasBunSqlImport: boolean }} facts факти
+   * @returns {Promise<boolean>} true, якщо deps pg/pg-format/mysql2 або import sql з bun
+   */
+  jsBunDbSignal(cwd, facts) {
+    if (facts.hasBunSqlImport === true) return true
+    return anyDepInTree(cwd, ['pg', 'pg-format', 'mysql2'])
+  },
+  /**
+   * @param {string} cwd корінь репо
+   * @returns {Promise<boolean>} true, якщо вкладений package.json без vite
+   */
+  nestedPackageWithoutVite(cwd) {
+    return nestedWithoutVite(cwd)
+  }
+}

package/scripts/lib/run-conftest-batch.mjs

@@ -0,0 +1,124 @@
+/**
+ * Запускає `conftest test` на batched-списку файлів і повертає всі порушення
+ * у структурованому вигляді. Використовується з `check-*.mjs`-скриптів, де
+ * пер-документні правила винесені у `npm/policy/<rule>/<name>/` як rego-полісі
+ * (Rego-authoritative). JS у `check-*.mjs` робить cross-file частину (walking
+ * дерева, парність, kustomize-резолюція), а пер-документне валідаційне ядро
+ * делегується сюді — один спавн `conftest` на (`namespace`, `policyDir`),
+ * незалежно від кількості файлів. Це закриває дублювання JS↔rego і прибирає
+ * ризик дрифту (типу `spec.config` vs `spec.default.config` у
+ * `health_check_policy.rego`, що ми ловили cross-check тестами).
+ *
+ * Hard-fail на відсутність `conftest` — через `ensureTool`, що спочатку
+ * намагається авто-встановити, і лише після невдачі кидає виняток.
+ */
+import { spawnSync } from 'node:child_process'
+import { existsSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import { ensureTool } from './ensure-tool.mjs'
+
+/**
+  Каталог пакета `@7n/rules`, від якого ресолвимо вшиті директорії правил.
+ */
+const PACKAGE_ROOT = dirname(dirname(dirname(fileURLToPath(import.meta.url))))
+
+/** Шлях до кореня правил. У npm-tarball публікується через `files: ["rules"]`. Кожне правило: `rules/<id>/policy/<name>/`. */
+const RULES_ROOT = join(PACKAGE_ROOT, 'rules')
+
+/**
+ * @typedef {object} ConftestViolation
+ * @property {string} filename абсолютний шлях до файла, що дав порушення (з output conftest)
+ * @property {string} message текст порушення (як у `deny` rego-пакета)
+ * @property {string} namespace namespace rego-пакета (наприклад `abie.base_deployment_preem`)
+ */
+
+/**
+ * @typedef {object} ConftestBatchOptions
+ * @property {string} policyDirRel шлях до підкаталогу `npm/policy/...` (наприклад `abie/base_deployment_preem`)
+ * @property {string} namespace повне імʼя rego-пакета (наприклад `abie.base_deployment_preem`)
+ * @property {string[]} files список абсолютних шляхів файлів для перевірки (порожній — повертаємо порожньо)
+ * @property {string[]} [extraArgs] додаткові аргументи для conftest (наприклад `--combine` для крос-документних правил)
+ * @property {object} [templateData] опціональне merged-дерево; серіалізується у JSON `{ "template": <data> }` і передається як `--data <tmpfile>` (cleanup після завершення)
+ */
+
+/**
+ * Pure args builder for conftest test. Extracted for unit-testability.
+ * Preserves the existing args layout (files before -p; --output json --no-color
+ * for parseable output); inserts --data right after --namespace when provided.
+ * @param {{ policyAbs: string, namespace: string, files: string[], extraArgs: string[], tmpDataFile: string|null }} p параметри батчу
+ * @returns {string[]} args для виклику conftest
+ */
+export function buildConftestArgs(p) {
+  const args = ['test', ...p.files, '-p', p.policyAbs, '--namespace', p.namespace]
+  if (p.tmpDataFile) args.push('--data', p.tmpDataFile)
+  args.push('--output', 'json', '--no-color', ...p.extraArgs)
+  return args
+}
+
+/**
+ * Виконує `conftest test` для всіх файлів одним спавном і повертає масив
+ * порушень. Якщо `files` порожній — повертає `[]` без спавна. Якщо `conftest`
+ * не у PATH і авто-встановлення не вдалось — кидає виняток (hard fail).
+ * @param {ConftestBatchOptions} opts параметри запуску
+ * @returns {ConftestViolation[]} масив порушень (порожній — все ок)
+ */
+export function runConftestBatch(opts) {
+  if (opts.files.length === 0) return []
+  const conftestBin = ensureTool('conftest')
+  // policyDirRel — формат `<rule>/<concern>` (наприклад `abie/base_deployment_preem`).
+  // Flat concern path: rules/<rule>/<concern>/ (без проміжного `policy/`).
+  const slash = opts.policyDirRel.indexOf('/')
+  const ruleId = slash === -1 ? opts.policyDirRel : opts.policyDirRel.slice(0, slash)
+  const sub = slash === -1 ? '' : opts.policyDirRel.slice(slash + 1)
+  const policyAbs = sub ? join(RULES_ROOT, ruleId, sub) : join(RULES_ROOT, ruleId)
+  if (!existsSync(policyAbs)) {
+    throw new Error(`runConftestBatch: rego-каталог не знайдено: ${policyAbs}`)
+  }
+  let tmpDataDir = null
+  let tmpDataFile = null
+  if (opts.templateData) {
+    tmpDataDir = mkdtempSync(join(tmpdir(), 'n-rules-tpl-'))
+    tmpDataFile = join(tmpDataDir, 'template-data.json')
+    writeFileSync(tmpDataFile, JSON.stringify({ template: opts.templateData }))
+  }
+  try {
+    const args = buildConftestArgs({
+      policyAbs,
+      namespace: opts.namespace,
+      files: opts.files,
+      extraArgs: opts.extraArgs ?? [],
+      tmpDataFile
+    })
+    const result = spawnSync(conftestBin, args, { encoding: 'utf8' })
+    if (result.error) throw result.error
+    // conftest exit 1 = є failures (це валідно для нас); >1 = справжня помилка.
+    if (result.status !== 0 && result.status !== 1) {
+      throw new Error(`conftest exit ${result.status}: ${(result.stderr || result.stdout || '').slice(0, 500)}`)
+    }
+    /**
+  @type {Array<{ filename: string, namespace: string, failures?: Array<{ msg: string }> }>}
+     */
+    let parsed
+    try {
+      parsed = JSON.parse(result.stdout)
+    } catch {
+      throw new Error(`conftest stdout не парситься як JSON: ${(result.stdout || '').slice(0, 200)}`)
+    }
+    /**
+  @type {ConftestViolation[]}
+     */
+    const out = []
+    for (const entry of parsed) {
+      const failures = entry.failures ?? []
+      for (const f of failures) {
+        out.push({ filename: entry.filename, namespace: entry.namespace, message: f.msg })
+      }
+    }
+    return out
+  } finally {
+    if (tmpDataDir) rmSync(tmpDataDir, { recursive: true, force: true })
+  }
+}