@7n/rules 1.4.1 → 1.5.0

package/scripts/lib/docs/acp-runner.md

@@ -0,0 +1,58 @@
+---
+type: JS Module
+title: acp-runner.mjs
+resource: npm/scripts/lib/acp-runner.mjs
+---
+
+## Огляд
+
+Модуль виконує скіл через зовнішнього ACP-агента (Agent Client Protocol,
+agentclientprotocol.com) — JSON-RPC поверх stdio замість сирого piping
+`stdin`/`stdout` у CLI. Замінює колишній `runLlmCli` (`spawnSync` + `-p`/`exec -`)
+для раннерів `cursor`/`codex`/`claude` у `skills-cli.mjs`.
+
+`cursor` запускається через нативний ACP-режим `cursor-agent acp` (зовнішній
+бінарник у PATH). `codex`/`claude` — через офіційні бандловані адаптери
+(`@agentclientprotocol/codex-acp`, `@agentclientprotocol/claude-agent-acp`), що
+самі керують своїм рушієм — зовнішній бінарник `codex`/`claude` у PATH більше
+не потрібен.
+
+## Поведінка
+
+- `ACP_AGENT_COMMANDS` — команда запуску агента на провайдер: `cursor` — бінарник
+  у PATH; `codex`/`claude` — резолвляться з `bin`-запису бандлованого пакета-адаптера.
+- `stopReasonToExitCode` — мапить ACP `StopReason` прогону на exit code: `end_turn` → `0`,
+  усе інше (`max_tokens`, `max_turn_requests`, `refusal`, `cancelled`) → `1`.
+- `resolveAdapterBin` — резолвить абсолютний шлях до bin-файлу адаптера з його `package.json`.
+- `pickAutoPermissionOptionId` — обирає `PermissionOption` без участі людини:
+  `allow_always` > `allow_once` > перша опція. Паритет із non-interactive `-p`/`exec -`
+  режимом — скіл є явною user-invocation, тож дозволи на tool-calls не питаються
+  інтерактивно.
+- `AcpSkillClient` (internal) — ACP `Client` для скіл-раннера: `requestPermission`
+  автоапрувляє через `pickAutoPermissionOptionId`, `sessionUpdate` стрімить текстові
+  дельти (`agent_message_chunk`) у переданий `out`, `readTextFile`/`writeTextFile`
+  реалізовані напряму через `node:fs` (full-trust режим, без write-guard).
+- `runAcpRunner` — підʼєднується до агента (`initialize` → `newSession` → `prompt`),
+  повертає exit code за `stopReasonToExitCode`; при stopReason ≠ `end_turn` додатково
+  логує причину через `logError`.
+
+## Публічний API
+
+- `ACP_AGENT_COMMANDS` — таблиця команд запуску на провайдер.
+- `stopReasonToExitCode(stopReason)` — `StopReason` → `0 | 1`.
+- `resolveAdapterBin(adapterPackage)` — шлях до bin-файлу адаптера.
+- `pickAutoPermissionOptionId(options)` — `optionId` автообраного варіанту дозволу.
+- `runAcpRunner(kind, prompt, projectDir, logError, deps?)` — виконує скіл через
+  ACP-агента `kind` (`cursor`|`codex`|`claude`); `deps` — інжекти для тестів
+  (`acp`, `spawnFn`, `out`, `resolveAdapterBin`, `isBinaryInPath`).
+
+## Гарантії поведінки
+
+- Permission-реквести від агента автоапрувляться без інтерактивного проміту —
+  парність із колишнім non-interactive `-p`/`exec -` режимом (full user-trust,
+  без write-guard, як і в `@7n/llm-lib/agent-skill`).
+- `cursor` кидає, якщо `cursor-agent` відсутній у PATH (перевіряється до спавну
+  дочірнього процесу). `codex`/`claude` перевірки PATH не потребують — резолвляться
+  з установлених npm-залежностей.
+- Дочірній процес агента завжди завершується (`child.kill()`) у `finally`, незалежно
+  від результату прогону.

package/scripts/lib/docs/concern-meta.md

@@ -3,7 +3,7 @@ type: JS Module
 title: concern-meta.mjs
 resource: npm/scripts/lib/concern-meta.mjs
 docgen:
-  crc: 85be92d0
+  crc: 1675429b
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
   tier: local-min
   score: 100

package/scripts/lib/docs/read-n-rules-config-lite.md

@@ -3,7 +3,7 @@ type: JS Module
 title: read-n-rules-config-lite.mjs
 resource: npm/scripts/lib/read-n-rules-config-lite.mjs
 docgen:
-  crc: d7e64586
+  crc: b942af8d
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 100
 ---
@@ -24,3 +24,5 @@ isRuleEnabled — визначає, чи діє певне правило на
 ## Гарантії поведінки
 
 - Read-only: не виконує операцій запису (ФС/БД).
+
+**plugins:** LiteConfig містить `plugins` (масив npm-імен або `undefined`, якщо поля немає — тоді resolve-plugins робить автодетект).

package/scripts/lib/docs/resolve-plugins.md

@@ -0,0 +1,17 @@
+---
+type: JS Module
+title: resolve-plugins.mjs
+resource: npm/scripts/lib/resolve-plugins.mjs
+docgen:
+  crc: 4fbb42be
+---
+
+Резолв плагінів @7n/rules: визначає, які пакети-плагіни активні у проєкті, де їхні `rules/`-каталоги, які capabilities вони надають і які handlers надають.
+
+Джерело правди — поле `plugins: string[]` у `.n-rules.json`; воно завжди перекриває автодетект, а явний порожній масив означає «плагіни вимкнено». Якщо поля немає, `detectPluginsFromRepo` шукає файлові сигнали: наявність yml у `.github/workflows/` дає `@7n/rules-ci-github`, файл `azure-pipelines.yml` у корені — `@7n/rules-ci-azure` (реєстр `KNOWN_CI_PLUGINS`). Лише коли файлових сигналів немає, вмикається fallback за `repository.url` кореневого package.json (`github.com` → github, `dev.azure.com`/`visualstudio.com` → azure). Обидва сигнали дають обидва плагіни, жодного — порожній список.
+
+`ensurePluginInstalled` ставить відсутній плагін через `bun add -d` (пакет стає devDependency — зміна видима у diff). Будь-який фейл установки (offline, пакет не опублікований) — warning і graceful skip, ніколи не hard-fail: лінт і синк мають працювати без мережі.
+
+`resolvePlugins(projectRoot, config, options)` — головна функція: повертає масив `{name, packageRoot, rulesDir, manifest}` доступних плагінів з кешем на процес. `options.allowInstall: false` — hot-path режим (hook, lint): лише вже встановлені пакети, без `bun add`; `options.quiet: true` глушить warning-и (hook викликається на кожен файл). Плагін без каталогу `rules/` пропускається.
+
+Маніфест — блок `"n-rules"` у package.json плагіна: `capabilities` (масив рядків на кшталт `ci:github`, живлять гейт концернів `requires.capability`) і `contributes.handlers` (мапа extension-point → відносний шлях модуля). `getActiveCapabilities` агрегує capabilities усіх плагінів у Set; `getHandlers(point)` повертає абсолютні шляхи модулів-обробників (v1 — лише API, споживачі handlers з'являться у v2). `resolveRulesDirs` віддає впорядковані джерела правил: ядро завжди перше (його правила й концерни виграють колізії), далі плагіни у порядку списку. `clearPluginResolveCache` скидає кеш (для тестів).

package/scripts/lib/docs/run-conftest-batch.md

@@ -3,7 +3,7 @@ type: JS Module
 title: run-conftest-batch.mjs
 resource: npm/scripts/lib/run-conftest-batch.mjs
 docgen:
-  crc: c581ce48
+  crc: 1ae29233
 ---
 
 Файл запускає `conftest test` на заданому списку файлів, виявляючи порушення правил, визначених у Rego-полісіях. Він використовується для автоматизованої перевірки конфігураційних файлів на відповідність заданим вимогам. Результати перевірки повертаються у структурованому вигляді, що дозволяє інтегрувати результати в інші процеси валідації.
@@ -28,3 +28,5 @@ runConftestBatch: Запускає `conftest test` для заданого сп
 - Не використовує кешування.
 - Не перехоплює помилки, а завершує роботу з помилкою.
 - Не має взаємодії з мережею.
+
+**policyDirAbs:** опційний абсолютний шлях до policy-теки (правила з плагінів поза вбудованим rules/); за наявності має пріоритет над `policyDirRel`.

package/scripts/lib/lint-surface/docs/policy-lint-adapter.md

@@ -3,7 +3,7 @@ type: JS Module
 title: policy-lint-adapter.mjs
 resource: npm/scripts/lib/lint-surface/policy-lint-adapter.mjs
 docgen:
-  crc: c25338e7
+  crc: facc5e07
   model: openai-codex/gpt-5.5
   tier: cloud-avg
   score: 80
@@ -42,3 +42,5 @@ docgen:
 ## Гарантії поведінки
 
 - Read-only: не виконує операцій запису (ФС/БД).
+
+**Плагіни:** у `runConftestBatch` передається `policyDirAbs: cfg.policyDir` — policy-тека concern-а може жити поза вбудованим rules/ ядра.

package/scripts/lib/lint-surface/docs/run-detectors.md

@@ -3,7 +3,7 @@ type: JS Module
 title: run-detectors.mjs
 resource: npm/scripts/lib/lint-surface/run-detectors.mjs
 docgen:
-  crc: 984cc5be
+  crc: e8a0ec47
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 100
   issues: judge:inaccurate:0.98
@@ -30,3 +30,7 @@ detectAll виконує прохід лінтера у режим детекц
 ## Гарантії поведінки
 
 - Read-only: не виконує операцій запису (ФС/БД).
+
+**Multi-dir (плагіни):** `effectiveRulesDirs` додає rules-каталоги плагінів з `.n-rules.json` (hot-path: без install, quiet); `readLintConcernsByRuleMulti` зливає концерни за іменем (перший власник виграє) — плагін може додавати концерни до правила ядра (mixin).
+
+**Capability-гейт:** `filterByCapabilities` відкидає концерни з незадоволеним `requires.capability` (capabilities надають встановлені плагіни через маніфест `n-rules.capabilities`; явний `opts.capabilities` у тестах перекриває резолв).

package/scripts/lib/lint-surface/policy-lint-adapter.mjs

@@ -92,6 +92,8 @@ export async function evaluatePolicyConcern(ctx, cfg) {
   const templateData = await resolveConcernTemplateData(cfg.policyDir, { files: cfg.files })
   const denies = runConftestBatch({
     policyDirRel: `${ruleId}/${concernId}`,
+    // Абсолютний шлях теки concern-а — правило може жити поза вбудованим rules/ ядра (плагін).
+    policyDirAbs: cfg.policyDir,
     namespace,
     files,
     templateData

package/scripts/lib/lint-surface/run-detectors.mjs

@@ -17,6 +17,7 @@ import picomatch from 'picomatch'
 import { listConcerns } from '../concern-meta.mjs'
 import { collectChangedFilesSince, resolveChangedBase } from '../changed-files.mjs'
 import { readNRulesConfigLite, isRuleEnabled } from '../read-n-rules-config-lite.mjs'
+import { getActiveCapabilities, resolvePlugins } from '../resolve-plugins.mjs'
 import { runConcernDetector, DetectorError } from './detect.mjs'
 import { renderViolations, renderDiagnostics } from './render.mjs'
 import { createProgressReporter } from './progress.mjs'
@@ -83,6 +84,71 @@ async function readLintConcernsByRule(rulesDir) {
   return out
 }
 
+/**
+ * Rules-каталоги прогону: явний `opts.rulesDirs`, або базовий (`opts.rulesDir` ?? вбудований)
+ * плюс каталоги плагінів з `.n-rules.json` (hot-path: без install і без warning-шуму).
+ * @param {{ rulesDirs?: string[], rulesDir?: string, cwd: string }} opts опції прогону.
+ * @returns {Promise<string[]>} упорядковані rules-каталоги (ядро перше).
+ */
+async function effectiveRulesDirs(opts) {
+  if (Array.isArray(opts.rulesDirs) && opts.rulesDirs.length > 0) return opts.rulesDirs
+  const base = opts.rulesDir ?? DEFAULT_RULES_DIR
+  const config = await readNRulesConfigLite(opts.cwd)
+  const plugins = resolvePlugins(opts.cwd, { plugins: config.plugins }, { allowInstall: false, quiet: true })
+  return [base, ...plugins.map(p => p.rulesDir)]
+}
+
+/**
+ * Відкидає концерни з незадоволеним `requires.capability`: capability надають
+ * встановлені плагіни (маніфест `n-rules.capabilities`). Явний `opts.capabilities`
+ * (тести) перекриває резолв.
+ * @param {Record<string, ConcernMeta[]>} byRule concerns за rule-id.
+ * @param {{ capabilities?: Iterable<string>, cwd: string }} opts опції прогону.
+ * @returns {Promise<Record<string, ConcernMeta[]>>} відфільтровані concerns.
+ */
+async function filterByCapabilities(byRule, opts) {
+  let caps
+  if (opts.capabilities) {
+    caps = new Set(opts.capabilities)
+  } else {
+    const config = await readNRulesConfigLite(opts.cwd)
+    caps = getActiveCapabilities(opts.cwd, { plugins: config.plugins }, { allowInstall: false, quiet: true })
+  }
+  /** @type {Record<string, ConcernMeta[]>} */
+  const out = {}
+  for (const [ruleId, concerns] of Object.entries(byRule)) {
+    const kept = concerns.filter(c => c.requiresCapability === undefined || caps.has(c.requiresCapability))
+    if (kept.length > 0) out[ruleId] = kept
+  }
+  return out
+}
+
+/**
+ * Мердж concerns кількох rules-каталогів: правила зливаються за id, концерни — за іменем
+ * (перший власник виграє: ядро → плагіни у порядку списку). Плагін може ДОДАВАТИ концерни
+ * до правила ядра (mixin), але не перекривати наявні.
+ * @param {string[]} rulesDirs упорядковані rules-каталоги.
+ * @returns {Promise<Record<string, ConcernMeta[]>>} об'єднані concerns за rule-id.
+ */
+async function readLintConcernsByRuleMulti(rulesDirs) {
+  /** @type {Record<string, ConcernMeta[]>} */
+  const merged = {}
+  for (const dir of rulesDirs) {
+    const byRule = await readLintConcernsByRule(dir)
+    for (const [ruleId, concerns] of Object.entries(byRule)) {
+      if (!(ruleId in merged)) {
+        merged[ruleId] = [...concerns]
+        continue
+      }
+      const seen = new Set(merged[ruleId].map(c => c.name))
+      for (const c of concerns) {
+        if (!seen.has(c.name)) merged[ruleId].push(c)
+      }
+    }
+  }
+  return merged
+}
+
 /**
  * Активні rule-id з `.n-rules.json` (для delta/full режимів).
  * @param {Record<string, ConcernMeta[]>} byRule concerns згруповані за rule-id.
@@ -111,7 +177,8 @@ function sortEntries(entries) {
  * Будує план прогону для заданих опцій (discovery + scope-table).
  * Спільне джерело для detect-only і fix-pipeline.
  * @param {object} opts опції прогону.
- * @param {string} opts.rulesDir корінь із правилами.
+ * @param {string} [opts.rulesDir] базовий корінь із правилами (дефолт — вбудований).
+ * @param {string[]} [opts.rulesDirs] явні rules-каталоги (ядро + плагіни); без них — базовий + плагіни з конфігу.
  * @param {string} opts.cwd робоча директорія прогону.
  * @param {boolean} [opts.full] whole-repo режим (усі enabled-concerns).
  * @param {string[]} [opts.rules] scoped rule-id (порожній → delta/full).
@@ -119,7 +186,7 @@ function sortEntries(entries) {
  * @returns {Promise<PlanItem[]>} впорядкований план прогону.
  */
 export async function buildDetectPlan(opts) {
-  const byRule = await readLintConcernsByRule(opts.rulesDir ?? DEFAULT_RULES_DIR)
+  const byRule = await filterByCapabilities(await readLintConcernsByRuleMulti(await effectiveRulesDirs(opts)), opts)
   return buildPlan({
     byRule,
     full: opts.full === true,
@@ -231,7 +298,8 @@ async function buildPlan({ byRule, full, rules, explicitFiles, cwd }) {
 /**
  * Запускає detect-only прохід. Повертає всі violations і похідний exitCode.
  * @param {object} opts опції прогону.
- * @param {string} opts.rulesDir корінь із правилами.
+ * @param {string} [opts.rulesDir] базовий корінь із правилами (дефолт — вбудований).
+ * @param {string[]} [opts.rulesDirs] явні rules-каталоги (ядро + плагіни); без них — базовий + плагіни з конфігу.
  * @param {string} opts.cwd робоча директорія прогону.
  * @param {boolean} [opts.full] whole-repo режим.
  * @param {string[]} [opts.rules] scoped rule-id (порожній → delta/full).
@@ -243,7 +311,6 @@ async function buildPlan({ byRule, full, rules, explicitFiles, cwd }) {
  * @returns {Promise<{ violations: LintViolation[], exitCode: 0|1|2, ran: LintEntry[] }>} violations, exitCode і виконані entries.
  */
 export async function detectAll(opts) {
-  const rulesDir = opts.rulesDir ?? DEFAULT_RULES_DIR
   const { cwd } = opts
   const full = opts.full === true
   const rules = Array.isArray(opts.rules) ? opts.rules : []
@@ -251,7 +318,7 @@ export async function detectAll(opts) {
   const verbose = opts.verbose === true
   const baseLog = opts.log ?? (s => process.stdout.write(s))
 
-  const byRule = await readLintConcernsByRule(rulesDir)
+  const byRule = await filterByCapabilities(await readLintConcernsByRuleMulti(await effectiveRulesDirs(opts)), opts)
   const plan = await buildPlan({ byRule, full, rules, explicitFiles, cwd })
 
   // Detect-only бар — ЛИШЕ в TTY (без тикера «виправлено»). У не-TTY (hooks, CI-gate,

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

@@ -22,6 +22,7 @@ const LEGACY_CONFIG_FILE = '.n-cursor.json'
  * @property {boolean} exists чи існує .n-rules.json (або legacy .n-rules.json) у поточному каталозі
  * @property {string[]} rules id правил з whitelist (порожній якщо файл відсутній)
  * @property {string[]} disableRules id правил, явно вимкнених у `disable-rules`
+ * @property {string[] | undefined} plugins npm-пакети-плагіни з конфігу; undefined — поля немає (→ автодетект у resolve-plugins)
  */
 
 /**
@@ -34,16 +35,17 @@ export async function readNRulesConfigLite(cwd = process.cwd()) {
     configPath = join(cwd, LEGACY_CONFIG_FILE)
   }
   if (!existsSync(configPath)) {
-    return { exists: false, rules: [], disableRules: [] }
+    return { exists: false, rules: [], disableRules: [], plugins: undefined }
   }
   const raw = await readFile(configPath, 'utf8')
-  /** @type {{ rules?: unknown, ['disable-rules']?: unknown }} */
+  /** @type {{ rules?: unknown, ['disable-rules']?: unknown, plugins?: 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 }
+  const plugins = Array.isArray(parsed.plugins) ? parsed.plugins.filter(p => typeof p === 'string') : undefined
+  return { exists: true, rules, disableRules, plugins }
 }
 
 /**

package/scripts/lib/resolve-plugins.mjs

@@ -0,0 +1,248 @@
+/**
+ * Резолв плагінів `@7n/rules`: які пакети-плагіни активні у проєкті, де їхні `rules/`,
+ * які capabilities вони дають і які handlers надають.
+ *
+ * Джерело правди — поле `plugins: string[]` у `.n-rules.json` (завжди перекриває автодетект;
+ * явний `[]` = «плагіни вимкнено»). Якщо поля немає — `detectPluginsFromRepo`: файлові сигнали
+ * (`.github/workflows/*.yml` → `@7n/rules-ci-github`; `azure-pipelines.yml` → `@7n/rules-ci-azure`),
+ * а без них — fallback за `repository.url` кореневого package.json (`github.com` / `dev.azure.com`).
+ *
+ * Установка: `ensurePluginInstalled` — плагін стає devDependency через `bun add -d` (bun сам
+ * резолвить актуальну версію; зміна видима у diff package.json). Фейл установки (offline,
+ * пакет ще не опублікований) — warning + graceful skip, ніколи не hard-fail: лінт/синк
+ * мають працювати без мережі. Hot-path (hook) НЕ встановлює — лише резолвить уже встановлені
+ * (`allowInstall: false`).
+ *
+ * Маніфест плагіна — блок `"n-rules"` у його package.json:
+ * `{ "capabilities": ["ci:github"], "contributes": { "rules": true, "handlers": { "<point>": "./mod.mjs" } } }`.
+ * `capabilities` живлять гейт концернів (`concern.json` → `requires.capability`);
+ * `handlers` — іменовані extension-points правил ядра (v1: лише API, споживачі — v2).
+ */
+import { existsSync, readdirSync, readFileSync } from 'node:fs'
+import { spawnSync } from 'node:child_process'
+import { join, resolve } from 'node:path'
+
+/** Відомі плагіни для автовизначення: сигнал у дереві репо → npm-пакет. */
+export const KNOWN_CI_PLUGINS = Object.freeze({
+  github: '@7n/rules-ci-github',
+  azure: '@7n/rules-ci-azure'
+})
+
+const WORKFLOW_YML_RE = /\.ya?ml$/u
+const GITHUB_URL_RE = /github\.com/iu
+const AZURE_URL_RE = /dev\.azure\.com|visualstudio\.com/iu
+
+/** Кеш резолву на процес: projectRoot → результат `resolvePlugins`. */
+const RESOLVE_CACHE = new Map()
+
+/**
+ * `repository.url` з кореневого package.json (string або {url}); null, якщо нема/нечитабельний.
+ * @param {string} projectRoot корінь репозиторію
+ * @returns {string | null} URL або null
+ */
+function readRepositoryUrl(projectRoot) {
+  try {
+    const pkg = JSON.parse(readFileSync(join(projectRoot, 'package.json'), 'utf8'))
+    const repo = pkg?.repository
+    if (typeof repo === 'string') return repo
+    if (repo && typeof repo === 'object' && typeof repo.url === 'string') return repo.url
+  } catch {
+    /* нема package.json або битий JSON — сигналу нема */
+  }
+  return null
+}
+
+/**
+ * Чи є у `.github/workflows/` хоч один yml/yaml.
+ * @param {string} projectRoot корінь репозиторію
+ * @returns {boolean} true — GitHub Actions присутні
+ */
+function hasGithubWorkflows(projectRoot) {
+  const dir = join(projectRoot, '.github', 'workflows')
+  if (!existsSync(dir)) return false
+  try {
+    return readdirSync(dir).some(name => WORKFLOW_YML_RE.test(name))
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Автодетект CI-плагінів за станом репозиторію.
+ * Файлові сигнали мають пріоритет; `repository.url` — лише коли файлових сигналів нема
+ * (свіже репо без CI-конфігів). Обидва сигнали → обидва плагіни; жодного → [].
+ * @param {string} projectRoot корінь репозиторію
+ * @returns {string[]} npm-імена плагінів
+ */
+export function detectPluginsFromRepo(projectRoot) {
+  const out = []
+  if (hasGithubWorkflows(projectRoot)) out.push(KNOWN_CI_PLUGINS.github)
+  if (existsSync(join(projectRoot, 'azure-pipelines.yml'))) out.push(KNOWN_CI_PLUGINS.azure)
+  if (out.length > 0) return out
+
+  const url = readRepositoryUrl(projectRoot)
+  if (typeof url === 'string') {
+    if (GITHUB_URL_RE.test(url)) out.push(KNOWN_CI_PLUGINS.github)
+    if (AZURE_URL_RE.test(url)) out.push(KNOWN_CI_PLUGINS.azure)
+  }
+  return out
+}
+
+/**
+ * Список плагінів проєкту: явний `config.plugins` (включно з порожнім = вимкнено) або автодетект.
+ * @param {string} projectRoot корінь репозиторію
+ * @param {{ plugins?: unknown } | null | undefined} config розпарсений `.n-rules.json` (може бути відсутній)
+ * @returns {string[]} npm-імена плагінів
+ */
+export function resolvePluginList(projectRoot, config) {
+  const declared = config?.plugins
+  if (Array.isArray(declared)) {
+    return declared.filter(p => typeof p === 'string' && p.trim() !== '')
+  }
+  return detectPluginsFromRepo(projectRoot)
+}
+
+/**
+ * Гарантує, що плагін встановлений: якщо `node_modules/<pkg>` нема — `bun add -d <pkg>`
+ * (дописує devDependency і ставить). Фейл — warning + false, без винятку.
+ * @param {string} projectRoot корінь репозиторію
+ * @param {string} packageName npm-ім'я плагіна
+ * @returns {boolean} true — пакет доступний у node_modules після виклику
+ */
+export function ensurePluginInstalled(projectRoot, packageName) {
+  const installed = join(projectRoot, 'node_modules', packageName, 'package.json')
+  if (existsSync(installed)) return true
+  if (!existsSync(join(projectRoot, 'package.json'))) return false
+
+  const r = spawnSync('bun', ['add', '-d', packageName], { cwd: projectRoot, encoding: 'utf8', shell: false })
+  if (r.error || r.status !== 0) {
+    const reason = r.error ? r.error.message : `bun add exit ${r.status}`
+    console.warn(`⚠️  Плагін ${packageName} не встановився (${reason}) — пропускаю\n`)
+    return false
+  }
+  return existsSync(installed)
+}
+
+/**
+ * @typedef {object} ResolvedPlugin
+ * @property {string} name npm-ім'я пакета (`@7n/rules` для ядра)
+ * @property {string} packageRoot абсолютний корінь пакета
+ * @property {string} rulesDir абсолютний шлях до `rules/` пакета
+ * @property {{ capabilities: string[], contributes: { rules?: boolean, handlers?: Record<string, string> } }} manifest нормалізований блок `n-rules` з package.json плагіна
+ */
+
+/**
+ * Маніфест плагіна з блоку `"n-rules"` його package.json (з дефолтами).
+ * @param {string} packageRoot корінь пакета
+ * @returns {ResolvedPlugin['manifest']} нормалізований маніфест
+ */
+function readPluginManifest(packageRoot) {
+  /** @type {ResolvedPlugin['manifest']} */
+  const fallback = { capabilities: [], contributes: { rules: true, handlers: {} } }
+  try {
+    const pkg = JSON.parse(readFileSync(join(packageRoot, 'package.json'), 'utf8'))
+    const raw = pkg?.['n-rules']
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return fallback
+    const capabilities = Array.isArray(raw.capabilities) ? raw.capabilities.filter(c => typeof c === 'string') : []
+    const contributes = raw.contributes && typeof raw.contributes === 'object' ? raw.contributes : {}
+    const handlers =
+      contributes.handlers && typeof contributes.handlers === 'object' && !Array.isArray(contributes.handlers)
+        ? Object.fromEntries(Object.entries(contributes.handlers).filter(([, v]) => typeof v === 'string'))
+        : {}
+    return { capabilities, contributes: { rules: contributes.rules !== false, handlers } }
+  } catch {
+    return fallback
+  }
+}
+
+/**
+ * Повний резолв плагінів проєкту (з кешем на процес).
+ * @param {string} projectRoot корінь репозиторію
+ * @param {{ plugins?: unknown } | null | undefined} config розпарсений `.n-rules.json`
+ * @param {{ allowInstall?: boolean, quiet?: boolean }} [options] `allowInstall:false` (hot-path hook/lint) —
+ *   лише вже встановлені пакети, без `bun add`; `quiet` — без warning-ів (hook на кожен файл)
+ * @returns {ResolvedPlugin[]} доступні плагіни (без ядра)
+ */
+export function resolvePlugins(projectRoot, config, options = {}) {
+  const root = resolve(projectRoot)
+  const names = resolvePluginList(root, config)
+  const cacheKey = `${root}${names.join(',')}${options.allowInstall !== false}`
+  const cached = RESOLVE_CACHE.get(cacheKey)
+  if (cached) return cached
+
+  /** @type {ResolvedPlugin[]} */
+  const out = []
+  for (const name of names) {
+    const packageRoot = join(root, 'node_modules', name)
+    const available =
+      existsSync(join(packageRoot, 'package.json')) ||
+      (options.allowInstall !== false && ensurePluginInstalled(root, name))
+    if (!available) {
+      if (options.allowInstall === false && options.quiet !== true) {
+        console.warn(`⚠️  Плагін ${name} не встановлений — пропускаю (запусти npx @7n/rules)\n`)
+      }
+      continue
+    }
+    const rulesDir = join(packageRoot, 'rules')
+    if (!existsSync(rulesDir)) {
+      if (options.quiet !== true) console.warn(`⚠️  Плагін ${name} без каталогу rules/ — пропускаю\n`)
+      continue
+    }
+    out.push({ name, packageRoot, rulesDir, manifest: readPluginManifest(packageRoot) })
+  }
+  RESOLVE_CACHE.set(cacheKey, out)
+  return out
+}
+
+/**
+ * Rules-каталоги для всіх поверхонь ядра: ядро першим (його правила/концерни виграють
+ * колізії), далі плагіни у порядку списку.
+ * @param {string} projectRoot корінь репозиторію
+ * @param {{ plugins?: unknown } | null | undefined} config розпарсений `.n-rules.json`
+ * @param {string} bundledRulesDir `rules/` встановленого/вбудованого ядра
+ * @param {{ allowInstall?: boolean }} [options] прокидається у `resolvePlugins`
+ * @returns {Array<{ name: string, rulesDir: string, packageRoot: string | null }>} джерела правил
+ */
+export function resolveRulesDirs(projectRoot, config, bundledRulesDir, options = {}) {
+  const plugins = resolvePlugins(projectRoot, config, options)
+  return [
+    { name: '@7n/rules', rulesDir: bundledRulesDir, packageRoot: null },
+    ...plugins.map(p => ({ name: p.name, rulesDir: p.rulesDir, packageRoot: p.packageRoot }))
+  ]
+}
+
+/**
+ * Активні capabilities від усіх доступних плагінів (для гейта `requires.capability` у concern.json).
+ * @param {string} projectRoot корінь репозиторію
+ * @param {{ plugins?: unknown } | null | undefined} config розпарсений `.n-rules.json`
+ * @param {{ allowInstall?: boolean }} [options] прокидається у `resolvePlugins`
+ * @returns {Set<string>} набір capability-рядків (напр. `ci:github`)
+ */
+export function getActiveCapabilities(projectRoot, config, options = {}) {
+  const caps = new Set()
+  for (const p of resolvePlugins(projectRoot, config, options)) {
+    for (const c of p.manifest.capabilities) caps.add(c)
+  }
+  return caps
+}
+
+/**
+ * Handlers для extension-point правила ядра (v1 — лише API; перший споживач — v2).
+ * @param {string} projectRoot корінь репозиторію
+ * @param {{ plugins?: unknown } | null | undefined} config розпарсений `.n-rules.json`
+ * @param {string} point ім'я extension-point (напр. `doc-files`)
+ * @returns {Array<{ pluginName: string, modulePath: string }>} абсолютні шляхи модулів-обробників
+ */
+export function getHandlers(projectRoot, config, point) {
+  const out = []
+  for (const p of resolvePlugins(projectRoot, config, { allowInstall: false })) {
+    const rel = p.manifest.contributes.handlers[point]
+    if (typeof rel === 'string') out.push({ pluginName: p.name, modulePath: join(p.packageRoot, rel) })
+  }
+  return out
+}
+
+/** Скидає кеш резолву (для тестів). */
+export function clearPluginResolveCache() {
+  RESOLVE_CACHE.clear()
+}

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

@@ -38,6 +38,8 @@ const RULES_ROOT = join(PACKAGE_ROOT, 'rules')
 /**
  * @typedef {object} ConftestBatchOptions
  * @property {string} policyDirRel шлях до підкаталогу `npm/policy/...` (наприклад `abie/base_deployment_preem`)
+ * @property {string} [policyDirAbs] абсолютний шлях до теки policy-concern-а — для правил ПОЗА вбудованим
+ *   `rules/` ядра (плагіни); за наявності має пріоритет над `policyDirRel`
  * @property {string} namespace повне імʼя rego-пакета (наприклад `abie.base_deployment_preem`)
  * @property {string[]} files список абсолютних шляхів файлів для перевірки (порожній — повертаємо порожньо)
  * @property {string[]} [extraArgs] додаткові аргументи для conftest (наприклад `--combine` для крос-документних правил)
@@ -73,7 +75,7 @@ export function runConftestBatch(opts) {
   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)
+  const policyAbs = opts.policyDirAbs ?? (sub ? join(RULES_ROOT, ruleId, sub) : join(RULES_ROOT, ruleId))
   if (!existsSync(policyAbs)) {
     throw new Error(`runConftestBatch: rego-каталог не знайдено: ${policyAbs}`)
   }