@7n/rules 1.14.0 → 1.15.0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## [1.15.0] - 2026-07-18
+
+### Added
+
+- Плагінна архітектура мовних екосистем (фаза 1 spec lang-plugins-extraction): новий порт `EcosystemProvider` у `@7n/rules/plugin-api` (detect/available/backup/bump/diff/promptFor/cleanup + `assertEcosystemProvider`), taze-оркестратор веде не-npm гілки генеричним циклом по провайдерах — Rust як вбудований first-party (`rust-provider.mjs`), Python/uv виїхав у окремий плагін `@7n/rules-lang-python` (автодетект за кореневим pyproject.toml, extension-point `taze` — перший реальний споживач handlers-API). Плагін без rules/ із `contributes.rules:false` тепер легальний (лише handlers); провал однієї екосистеми не зупиняє інших
+
+## [1.14.1] - 2026-07-18
+
+### Changed
+
+- docs(adr): brainstorm — внутрішній паралелізм lint-оркестратора (#86)
+- Оновлено внутрішній lint-оркестратор.
+
 ## [1.14.0] - 2026-07-18
 
 ### Changed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@7n/rules",
-  "version": "1.14.0",
+  "version": "1.15.0",
   "description": "CLI еталонних правил і skills (префікс n-): синк у репозиторій, дельта-lint, конформність",
   "keywords": [
     "cli",
@@ -51,6 +51,7 @@
   "exports": {
     ".": "./bin/n-rules.js",
     "./package.json": "./package.json",
+    "./plugin-api": "./scripts/lib/plugin-api.mjs",
     "./scripts/*": "./scripts/*",
     "./schemas/*": "./schemas/*",
     "./rules/*": "./rules/*"

package/rules/graphql/tooling/docs/main.md

@@ -3,7 +3,7 @@ type: JS Module
 title: main.mjs
 resource: npm/rules/graphql/tooling/main.mjs
 docgen:
-  crc: b165a889
+  crc: d341d8e0
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 100
   issues: judge:inaccurate:0.98

package/rules/graphql/tooling/main.mjs

@@ -67,10 +67,10 @@ async function collectGqlHits(root, candidates) {
  * (умовне правило — без gql цей крок не запускається).
  * @param {(msg: string) => void} pass success-репортер
  * @param {(msg: string) => void} fail fail-репортер
- * @returns {void}
+ * @returns {Promise<void>} результат
  * @param {string} cwd корінь репозиторію
  */
-function checkExtensionsRecommendation(pass, fail, cwd) {
+async function checkExtensionsRecommendation(pass, fail, cwd) {
   const pathRel = '.vscode/extensions.json'
   const pathAbs = join(cwd, pathRel)
   if (!existsSync(pathAbs)) {
@@ -79,7 +79,7 @@ function checkExtensionsRecommendation(pass, fail, cwd) {
     )
     return
   }
-  const violations = runConftestBatch({
+  const violations = await runConftestBatch({
     policyDirRel: 'graphql/vscode_extensions',
     namespace: 'graphql.vscode_extensions',
     files: [pathAbs]
@@ -123,7 +123,7 @@ export async function lint(ctx) {
     )
   }
 
-  checkExtensionsRecommendation(pass, fail, root)
+  await checkExtensionsRecommendation(pass, fail, root)
 
   return reporter.result()
 }

package/rules/js/eslint/docs/main.md

@@ -3,7 +3,7 @@ type: JS Module
 title: main.mjs
 resource: npm/rules/js/eslint/main.mjs
 docgen:
-  crc: fa1753b7
+  crc: e831a6e8
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 100
   issues: judge:inaccurate:0.99

package/rules/js/eslint/main.mjs

@@ -3,16 +3,15 @@
  * eslint --fix) — окремий T0 `fix-eslint.mjs` (детермінований), не в detector-і.
  */
 import { resolve, relative } from 'node:path'
-import { spawnSync } from 'node:child_process'
 
 import { ESLint } from 'eslint'
 
 import { addedLinesByFile } from '../../../scripts/lib/diff-added-lines.mjs'
+import { spawnAsync } from '../../../scripts/utils/spawn-async.mjs'
 import { WORKTREE_CHECKOUT_GLOBS } from '../../../scripts/utils/walkDir.mjs'
 import { classifyFindings, eslintResultsToFindings, parseOxlint } from '../lint-findings/main.mjs'
 
 const JS_EXT_RE = /\.(?:mjs|cjs|js|jsx|ts|tsx|vue)$/u
-const JSON_MAX_BUFFER = 64 * 1024 * 1024
 
 /**
  * @param {string[]} files список шляхів
@@ -23,13 +22,15 @@ export function filterJsFiles(files) {
 }
 
 /**
+ * Async (не блокує event loop) — детектор може виконуватись у parallel lane `detectAll()`
+ * (ADR 260716-1354).
  * @param {string[]} args аргументи запуску oxlint
  * @param {string} cwd робочий каталог
- * @returns {{ status: number, stdout: string, stderr: string }} код завершення, stdout і stderr процесу
+ * @returns {Promise<{ status: number, stdout: string, stderr: string }>} код завершення, stdout і stderr процесу
  */
-function runOxlintJson(args, cwd) {
-  const r = spawnSync('bunx', args, { cwd, encoding: 'utf8', maxBuffer: JSON_MAX_BUFFER })
-  return { status: typeof r.status === 'number' ? r.status : 1, stdout: r.stdout ?? '', stderr: r.stderr ?? '' }
+async function runOxlintJson(args, cwd) {
+  const r = await spawnAsync('bunx', args, { cwd })
+  return { status: typeof r.exitCode === 'number' ? r.exitCode : 1, stdout: r.stdout ?? '', stderr: r.stderr ?? '' }
 }
 
 /**
@@ -68,7 +69,7 @@ async function collectFindings(js, cwd) {
     js === null
       ? ['oxlint', '--format=json', ...worktreeIgnoreArgs]
       : ['oxlint', '--format=json', ...worktreeIgnoreArgs, ...js]
-  const oxRes = runOxlintJson(oxArgs, cwd)
+  const oxRes = await runOxlintJson(oxArgs, cwd)
   const ox = parseOxlint(oxRes.stdout)
   if (ox === null && oxRes.status !== 0) {
     // Хвости stdout/stderr — інакше на CI причина крашу (OOM, конфіг, версія) невидима.

package/rules/js-run/runtime/docs/main.md

@@ -3,7 +3,7 @@ type: JS Module
 title: main.mjs
 resource: npm/rules/js-run/runtime/main.mjs
 docgen:
-  crc: e50892ad
+  crc: 9f11393b
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 100
   issues: judge:inaccurate:0.99

package/rules/js-run/runtime/main.mjs

@@ -45,10 +45,10 @@ function backendPackageHasSrcDir(absPackageRoot) {
  * @param {string} label префікс `[pkg] `
  * @param {(msg: string) => void} fail callback для повідомлень про порушення
  * @param {(msg: string) => void} passFn callback для повідомлень про успішну перевірку
- * @returns {void}
+ * @returns {Promise<void>} результат
  * @param {string} cwd корінь репозиторію
  */
-function checkBackendJsconfigWhenSrcPresent(rootDir, absPackageRoot, label, fail, passFn, cwd) {
+async function checkBackendJsconfigWhenSrcPresent(rootDir, absPackageRoot, label, fail, passFn, cwd) {
   if (!backendPackageHasSrcDir(absPackageRoot)) return
 
   const jcPath = join(cwd, rootDir, 'jsconfig.json')
@@ -59,7 +59,7 @@ function checkBackendJsconfigWhenSrcPresent(rootDir, absPackageRoot, label, fail
     )
     return
   }
-  const violations = runConftestBatch({
+  const violations = await runConftestBatch({
     policyDirRel: 'js-run/jsconfig',
     namespace: 'js_run.jsconfig',
     files: [jcPath]

package/rules/k8s/manifests/main.mjs

@@ -3201,7 +3201,7 @@ async function validateHasuraHttpRouteCanon(root, yamlFiles, fail) {
     }
   }
   if (pairedFiles.size === 0) return
-  const violations = runConftestBatch({
+  const violations = await runConftestBatch({
     policyDirRel: 'k8s/hasura_httproute',
     namespace: 'k8s.hasura_httproute',
     files: [...pairedFiles]
@@ -3626,7 +3626,7 @@ async function validateHasuraConfigMapRemoteSchemaPermissions(root, yamlFilesAbs
     }
   }
   if (paired.length === 0) return
-  const violations = runConftestBatch({
+  const violations = await runConftestBatch({
     policyDirRel: 'k8s/hasura_configmap',
     namespace: 'k8s.hasura_configmap',
     files: paired
@@ -6604,9 +6604,9 @@ function k8sRegoFixHint(ns, file, message) {
  * @param {string} root корінь репозиторію.
  * @param {string[]} yamlFiles абсолютні шляхи *.yaml під `…/k8s/`.
  * @param {(msg: string, hint?: unknown) => void} fail callback реєстрації порушення.
- * @returns {void}
+ * @returns {Promise<void>} результат
  */
-function runAllK8sRego(root, yamlFiles, fail) {
+async function runAllK8sRego(root, yamlFiles, fail) {
   const relOf = abs => relative(root, abs).replaceAll('\\', '/') || abs
 
   const allYaml = yamlFiles
@@ -6645,7 +6645,7 @@ function runAllK8sRego(root, yamlFiles, fail) {
 
   for (const t of targets) {
     if (t.files.length === 0) continue
-    const violations = runConftestBatch({
+    const violations = await runConftestBatch({
       policyDirRel: t.dir,
       namespace: t.ns,
       files: t.files,
@@ -6707,7 +6707,7 @@ export async function lint(ctx) {
   // Plan B: пер-документні структурні правила — у rego-полісі `npm/policy/k8s/*`,
   // викликаємо одним батчем на namespace через runConftestBatch. JS нижче робить
   // лише cross-file orchestration, modeline та FS-existence перевірки.
-  runAllK8sRego(root, yamlFiles, fail)
+  await runAllK8sRego(root, yamlFiles, fail)
   pass(`Rego-полісі (npm/policy/k8s/*) виконано на ${yamlFiles.length} файл(ах)`)
 
   for (const abs of yamlFiles) {

package/rules/nginx-default-tpl/template/docs/main.md

@@ -3,7 +3,7 @@ type: JS Module
 title: main.mjs
 resource: npm/rules/nginx-default-tpl/template/main.mjs
 docgen:
-  crc: e45b3d5f
+  crc: 1197df15
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 100
   issues: judge:inaccurate:0.99

package/rules/nginx-default-tpl/template/main.mjs

@@ -378,12 +378,12 @@ async function checkDockerfiles(root, ignorePaths, passFn, failFn) {
  * @param {(msg: string) => void} passFn callback при успішній перевірці
  * @param {(msg: string) => void} failFn callback при помилці
  * @param {string} cwd корінь репозиторію
- * @returns {void}
+ * @returns {Promise<void>} результат
  */
-function checkVscodeNginx(passFn, failFn, cwd) {
+async function checkVscodeNginx(passFn, failFn, cwd) {
   const extPath = join(cwd, '.vscode/extensions.json')
   if (existsSync(extPath)) {
-    const violations = runConftestBatch({
+    const violations = await runConftestBatch({
       policyDirRel: 'nginx-default-tpl/vscode_extensions',
       namespace: 'nginx_default_tpl.vscode_extensions',
       files: [extPath]
@@ -402,7 +402,7 @@ function checkVscodeNginx(passFn, failFn, cwd) {
     failFn('Очікується .vscode/settings.json з форматером nginx і formatOnSave (див. nginx-default-tpl.mdc)')
     return
   }
-  const violations = runConftestBatch({
+  const violations = await runConftestBatch({
     policyDirRel: 'nginx-default-tpl/vscode_settings',
     namespace: 'nginx_default_tpl.vscode_settings',
     files: [setPath]
@@ -499,7 +499,7 @@ export async function lint(ctx) {
   }
 
   await checkDockerfiles(root, ignorePaths, pass, fail)
-  checkVscodeNginx(pass, fail, root)
+  await checkVscodeNginx(pass, fail, root)
 
   return reporter.result()
 }

package/rules/tauri/tooling/docs/main.md

@@ -3,7 +3,7 @@ type: JS Module
 title: main.mjs
 resource: npm/rules/tauri/tooling/main.mjs
 docgen:
-  crc: 7c892c9b
+  crc: 4b6ecb02
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 95
   issues: anchor-miss:(tauri.mdc),judge:inaccurate:0.97

package/rules/tauri/tooling/main.mjs

@@ -79,7 +79,7 @@ export async function lint(ctx) {
     fail(`${extPath} не існує — створи з recommendations "tauri-apps.tauri-vscode" (tauri.mdc)`)
     return reporter.result()
   }
-  const violations = runConftestBatch({
+  const violations = await runConftestBatch({
     policyDirRel: 'tauri/vscode_extensions',
     namespace: 'tauri.vscode_extensions',
     files: [extPath]

package/scripts/lib/docs/ensure-tool.md

@@ -3,7 +3,7 @@ type: JS Module
 title: ensure-tool.mjs
 resource: npm/scripts/lib/ensure-tool.mjs
 docgen:
-  crc: 42b0cd01
+  crc: b1b054d0
 ---
 
 Модуль `ensure-tool.mjs` — єдина точка резолву зовнішніх CLI-залежностей пакета `@7n/rules`. Він гарантує, що потрібний бінарник (`hk`, `conftest`, `shellcheck`, `actionlint`, `dotenv-linter`, `opa`, `regal`, `hadolint`, `kubeconform`, `kubescape`) доступний у системі, виконуючи послідовний пошук:
@@ -15,14 +15,17 @@ docgen:
 
 Така архітектура усуває дублювання install-логіки в кожному `lint.mjs` / `fix.mjs`: щоб додати нову зовнішню утиліту, достатньо одного запису в реєстрі `TOOLS`. Додатково модуль експортує `ensureHkInstall`, який реєструє git pre-commit hook через `hk install` (пропускається в CI).
 
-Файл написаний для Node.js (ESM), використовує лише стандартну бібліотеку та один локальний хелпер `resolveCmd`.
+Поруч із синхронною `ensureTool` (публічний API пакета, сигнатура не змінюється) модуль експортує async-варіант `ensureToolAsync(toolId)` для parallel lane `detectAll()` (ADR 260716-1354-внутрішній-паралелізм-lint-оркестратора): конкурентні виклики того самого `toolId` в одному Node-процесі колапсують в один install (in-process single-flight), а auto-install крок додатково серіалізується між процесами через `withLock` (ключ `ensure-tool/<toolId>`) — паралельні Node-процеси (різні CI-shard-и, кілька агентів) не тягнуть той самий бінарник конкурентно. Завантажений архів завжди пишеться в унікальний per-call temp-каталог і публікується атомарним `renameSync` під фіксованим flat-іменем `<toolId>` — цей hardened install-крок спільний для sync і async шляхів.
+
+Файл написаний для Node.js (ESM), використовує лише стандартну бібліотеку, локальний хелпер `resolveCmd` і `withLock` (`../utils/with-lock.mjs`) для міжпроцесної серіалізації async-install-кроку.
 
 ## Експорти / API
 
-| Експорт                  | Тип        | Призначення                                                                                                    |
-| ------------------------ | ---------- | -------------------------------------------------------------------------------------------------------------- |
-| `ensureTool(toolId)`     | `function` | Резолвить і за потреби встановлює зовнішній CLI. Повертає абсолютний шлях до бінарника або кидає `Error`.      |
-| `ensureHkInstall(hkBin)` | `function` | Виконує `hk install` для реєстрації git pre-commit hook. Жодного return value; на помилку лише `console.warn`. |
+| Експорт                    | Тип        | Призначення                                                                                                                                       |
+| --------------------------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ensureTool(toolId)`        | `function` | Резолвить і за потреби встановлює зовнішній CLI (sync). Повертає абсолютний шлях до бінарника або кидає `Error`.                                     |
+| `ensureToolAsync(toolId)`   | `function` | Async-варіант для parallel lane `detectAll()`: single-flight (in-process) + `withLock` (cross-process) навколо auto-install кроку. Повертає `Promise<string>`. |
+| `ensureHkInstall(hkBin)`    | `function` | Виконує `hk install` для реєстрації git pre-commit hook. Жодного return value; на помилку лише `console.warn`.                                       |
 
 Внутрішні (не експортуються, але формують контракт модуля):
 
@@ -81,19 +84,18 @@ docgen:
   1. Резолвить `curl` та `tar` у PATH; за відсутності — кидає `Error`.
   2. Через `fetchLatestVersion` отримує актуальну версію.
   3. Формує назву asset через `entry.asset(ver)` і URL `https://github.com/<github>/releases/download/v<ver>/<asset>`.
-  4. Створює `cacheDir` (`mkdirSync` з `recursive: true`).
-  5. Завантажує asset через `curl -sSL -o <archivePath> <downloadUrl>`.
-  6. Якщо `entry.archive === false` — перейменовує завантажений файл у `<cacheDir>/<toolId>`, виставляє права `0o755` і повертає шлях.
-  7. Інакше викликає `tar` із прапорцем `-xJf` (для `.tar.xz`) або `-xzf` (для `.tar.gz`) для розпакування в `cacheDir`.
-  8. Визначає реальний шлях до бінарника через `entry.binFinder(ver)` або просто `toolId`. Перевіряє існування файлу.
-  9. Опціонально видаляє завантажений архів через `rm` (м’яко: якщо `rm` не знайдено, продовжує).
+  4. Створює `cacheDir` (`mkdirSync` з `recursive: true`) і унікальний per-call temp-каталог усередині нього (`mkdtempSync(join(cacheDir, '.tmp-<toolId>-'))`) — той самий filesystem гарантує, що фінальний `renameSync` не впаде з `EXDEV`.
+  5. Завантажує asset у temp-каталог через `curl -sSL -o <tmpDir>/<asset> <downloadUrl>`.
+  6. Якщо `entry.archive === false` — `chmodSync` завантаженого файлу (`0o755`) і атомарний `renameSync` у `<cacheDir>/<toolId>`.
+  7. Інакше викликає `tar` із прапорцем `-xJf` (для `.tar.xz`) або `-xzf` (для `.tar.gz`) для розпакування в temp-каталог, знаходить реальний шлях бінарника через `entry.binFinder(ver)` або просто `toolId`, перевіряє його існування — і так само атомарним `renameSync` публікує його у `<cacheDir>/<toolId>` (flat-ім'я, незалежно від вкладеної структури архіву).
+  8. У `finally` прибирає весь temp-каталог (`rmSync(tmpDir, { recursive: true, force: true })`) — і архів, і проміжні файли розпакування зникають одним викликом.
 - **Помилки:**
   - `curl не знайдено в PATH — потрібен для завантаження <toolId>`.
   - `tar не знайдено в PATH — потрібен для встановлення <toolId>`.
   - `Завантаження <toolId> не вдалось: ...` / `curl exit <status> при завантаженні <toolId>: ...`.
   - `tar failed for <toolId>: ...` / `tar exit <status> для <toolId>: ...`.
-  - `Бінарник <toolId> не знайдено після розпакування: <binPath>`.
-- **Side effects:** мережа, файлова система (створення/перейменування файлів, chmod, видалення архіву).
+  - `Бінарник <toolId> не знайдено після розпакування: <extractedBin>`.
+- **Side effects:** мережа, файлова система (унікальний temp-каталог, атомарна публікація, chmod, очищення temp).
 
 ### `installViaBrew(toolId, entry)`
 
@@ -149,7 +151,7 @@ docgen:
 - **Послідовність резолву:**
   1. **Валідація** — якщо `TOOLS[toolId]` відсутній, кидає `ensureTool: невідомий тул '<toolId>'`.
   2. **PATH** — `resolveCmd(toolId)`; якщо знайдено — повертає одразу.
-  3. **Кеш** — `join(getCacheDir(), toolId)`; якщо файл існує — повертає його шлях. Зауваження: перевірка спрощена і не враховує `entry.binFinder` (для cached binaries `installFromGithub` уже клав фінальний бінарник у відоме місце або кеш просто не містить такого файлу — у такому разі переходимо до install).
+  3. **Кеш** — `join(getCacheDir(), toolId)`; якщо файл існує — повертає його шлях. Install завжди публікує бінарник під цим самим flat-іменем (атомарний `renameSync`, незалежно від вкладеної структури архіву — напр. `shellcheck` розпаковується у `shellcheck-v<ver>/shellcheck`), тож ця перевірка коректно бачить кеш і після `entry.binFinder`-архівів.
   4. **Авто-install** — якщо змінна середовища `N_CURSOR_NO_AUTO_INSTALL` не виставлена, викликає `autoInstall(toolId, entry, cacheDir)`.
   5. **Hard-fail** — кидає `Error(buildHint(toolId, entry))`.
 - **Помилки:** будь-яка з помилок `autoInstall` / `installFrom*` піднімається вгору; додатково — `невідомий тул` та `❌ ... не знайдено в PATH`.
@@ -209,13 +211,13 @@ docgen:
    - `fetchLatestVersion('koalaman/shellcheck', curl)` → наприклад `0.10.0`.
    - asset name = `shellcheck-v0.10.0.linux.x86_64.tar.xz`.
    - URL = `https://github.com/koalaman/shellcheck/releases/download/v0.10.0/<asset>`.
-   - `mkdirSync(cacheDir, { recursive: true })`.
-   - `curl -sSL -o <cacheDir>/<asset> <url>`.
-   - `tar -xJf <asset> -C <cacheDir>` (бо `.tar.xz`).
-   - `binFinder('0.10.0')` → `shellcheck-v0.10.0/shellcheck`.
-   - Перевірка `existsSync(<cacheDir>/shellcheck-v0.10.0/shellcheck)`.
-   - `rm <archivePath>`.
-   - Повертає `<cacheDir>/shellcheck-v0.10.0/shellcheck`.
+   - `mkdirSync(cacheDir, { recursive: true })` і унікальний `tmpDir = mkdtempSync(join(cacheDir, '.tmp-shellcheck-'))`.
+   - `curl -sSL -o <tmpDir>/<asset> <url>`.
+   - `tar -xJf <asset> -C <tmpDir>` (бо `.tar.xz`).
+   - `binFinder('0.10.0')` → `<tmpDir>/shellcheck-v0.10.0/shellcheck`; перевірка `existsSync`.
+   - Атомарний `renameSync(<tmpDir>/shellcheck-v0.10.0/shellcheck, <cacheDir>/shellcheck)` — публікація під flat-іменем.
+   - `rmSync(tmpDir, { recursive: true, force: true })` у `finally`.
+   - Повертає `<cacheDir>/shellcheck`.
 7. Викликач отримує абсолютний шлях і запускає `spawnSync(bin, [...args])`.
 
 ### Сценарій блокування авто-installу

package/scripts/lib/docs/index.md

@@ -6,6 +6,7 @@ resource: npm/scripts/lib/
 
 | Файл                                                                        | Тип       |
 | --------------------------------------------------------------------------- | --------- |
+| [acp-runner.mjs](acp-runner.md)                                             | JS Module |
 | [assert-project-root.mjs](assert-project-root.md)                           | JS Module |
 | [blue-oak.mjs](blue-oak.md)                                                 | JS Module |
 | [changed-files.mjs](changed-files.md)                                       | JS Module |
@@ -23,7 +24,9 @@ resource: npm/scripts/lib/
 | [list-rule-ids.mjs](list-rule-ids.md)                                       | JS Module |
 | [load-cursor-config.mjs](load-cursor-config.md)                             | JS Module |
 | [mirror-parity.mjs](mirror-parity.md)                                       | JS Module |
-| [read-n-rules-config-lite.mjs](read-n-rules-config-lite.md)               | JS Module |
+| [plugin-api.mjs](plugin-api.md)                                             | JS Module |
+| [read-n-rules-config-lite.mjs](read-n-rules-config-lite.md)                 | JS Module |
+| [resolve-plugins.mjs](resolve-plugins.md)                                   | JS Module |
 | [resolve-target-files.mjs](resolve-target-files.md)                         | JS Module |
 | [root-notice.mjs](root-notice.md)                                           | JS Module |
 | [rule-meta-helpers.mjs](rule-meta-helpers.md)                               | JS Module |

package/scripts/lib/docs/plugin-api.md

@@ -0,0 +1,31 @@
+---
+type: JS Module
+title: plugin-api.mjs
+resource: npm/scripts/lib/plugin-api.mjs
+docgen:
+  crc: dc4f4a12
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  tier: local-min-retry
+  score: 100
+  issues: judge:inaccurate:0.98
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+## Огляд
+
+Публічний API для плагінів `@7n/rules` (експорт `@7n/rules/plugin-api`). У фазі 1 (`spec 2026-07-18-lang-plugins-extraction`) реалізовано порт `EcosystemProvider` для `taze`. Плагін реєструє провайдера через маніфест `package.json`: `"n-rules": { "contributes": { "handlers": { "taze": "./taze/provider.mjs" } } }`, причому модуль-обробник експортує об'єкт провайдера як `default`. Публічні функції включають `PLUGIN_API_VERSION` та `assertEcosystemProvider`. Ядро реекспортує Semver-утиліти для коректної класифікації major/minor версій плагінами, використовуючи той самий принцип caret-семантики, що й ядро, без дублювання коду та імпорту внутрішніх шляхів `@7n/rules`.
+
+## Поведінка
+
+- PLUGIN_API_VERSION визначає версію контракту plugin-api.
+- assertEcosystemProvider перевіряє, чи об'єкт, наданий плагіном, відповідає очікуваній структурі EcosystemProvider, і викидає відповідну помилку, якщо він не валідний.
+
+## Публічний API
+
+- PLUGIN_API_VERSION — версія контракту plugin-api; плагін декларує `requiresPluginApi`, несумісність дає зрозумілий skip, не креш.
+- isBreaking / parseVersion — реекспорт semver-утиліт ядра для однакової класифікації major/minor у плагінах.
+- assertEcosystemProvider — перевіряє, чи має default-експорт handler-модуля плагіна необхідну форму EcosystemProvider, щоб система могла виявити помилку чітко замість непередбачуваної.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).

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

@@ -3,15 +3,15 @@ type: JS Module
 title: resolve-plugins.mjs
 resource: npm/scripts/lib/resolve-plugins.mjs
 docgen:
-  crc: 4fbb42be
+  crc: ef33c272
 ---
 
 Резолв плагінів @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). Обидва сигнали дають обидва плагіни, жодного — порожній список.
+Джерело правди — поле `plugins: string[]` у `.n-rules.json`; воно завжди перекриває автодетект, а явний порожній масив означає «плагіни вимкнено». Якщо поля немає, `detectPluginsFromRepo` шукає файлові сигнали: наявність yml у `.github/workflows/` дає `@7n/rules-ci-github`, файл `azure-pipelines.yml` у корені — `@7n/rules-ci-azure` (реєстр `KNOWN_CI_PLUGINS`). Лише коли файлових CI-сигналів немає, вмикається fallback за `repository.url` кореневого package.json (`github.com` → github, `dev.azure.com`/`visualstudio.com` → azure). Обидва сигнали дають обидва плагіни, жодного — порожній список. Окремо від CI детектяться мовні плагіни (реєстр `KNOWN_LANG_PLUGINS`, лише файлові сигнали, без URL-fallback): кореневий `pyproject.toml` → `@7n/rules-lang-python`.
 
 `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/` пропускається.
+`resolvePlugins(projectRoot, config, options)` — головна функція: повертає масив `{name, packageRoot, rulesDir, manifest}` доступних плагінів з кешем на процес. `options.allowInstall: false` — hot-path режим (hook, lint): лише вже встановлені пакети, без `bun add`; `options.quiet: true` глушить warning-и (hook викликається на кожен файл). Плагін, що декларує правила (`contributes.rules !== false`), але не має каталогу `rules/`, пропускається як битий; плагін із явним `contributes.rules: false` (лише handlers, як `lang-*`) — легальний, `resolveRulesDirs` його просто не включає у джерела правил.
 
-Маніфест — блок `"n-rules"` у package.json плагіна: `capabilities` (масив рядків на кшталт `ci:github`, живлять гейт концернів `requires.capability`) і `contributes.handlers` (мапа extension-point → відносний шлях модуля). `getActiveCapabilities` агрегує capabilities усіх плагінів у Set; `getHandlers(point)` повертає абсолютні шляхи модулів-обробників (v1 — лише API, споживачі handlers з'являться у v2). `resolveRulesDirs` віддає впорядковані джерела правил: ядро завжди перше (його правила й концерни виграють колізії), далі плагіни у порядку списку. `clearPluginResolveCache` скидає кеш (для тестів).
+Маніфест — блок `"n-rules"` у package.json плагіна: `capabilities` (масив рядків на кшталт `ci:github`, живлять гейт концернів `requires.capability`) і `contributes.handlers` (мапа extension-point → відносний шлях модуля). `getActiveCapabilities` агрегує capabilities усіх плагінів у Set; `getHandlers(point)` повертає абсолютні шляхи модулів-обробників (перший реальний споживач — taze-оркестратор, extension-point `taze`). `resolveRulesDirs` віддає впорядковані джерела правил: ядро завжди перше (його правила й концерни виграють колізії), далі плагіни у порядку списку. `clearPluginResolveCache` скидає кеш (для тестів).

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

@@ -3,20 +3,22 @@ type: JS Module
 title: run-conftest-batch.mjs
 resource: npm/scripts/lib/run-conftest-batch.mjs
 docgen:
-  crc: 1ae29233
+  crc: 39e76cec
 ---
 
 Файл запускає `conftest test` на заданому списку файлів, виявляючи порушення правил, визначених у Rego-полісіях. Він використовується для автоматизованої перевірки конфігураційних файлів на відповідність заданим вимогам. Результати перевірки повертаються у структурованому вигляді, що дозволяє інтегрувати результати в інші процеси валідації.
 
+`runConftestBatch` — **async** (ADR 260716-1354-внутрішній-паралелізм-lint-оркестратора): `conftest` запускається через non-blocking `spawnAsync` (не `spawnSync`), а бінарник резолвиться через `ensureToolAsync('conftest')` — це дозволяє функції брати участь у parallel lane `detectAll()` замість того, щоб блокувати event loop цілком. Приймає опційні `signal` (`AbortSignal`) і `timeoutMs`, обидва прокидаються у `spawnAsync`.
+
 ## Поведінка
 
 buildConftestArgs: Будує аргументи командного рядка для запуску `conftest test`, враховуючи список файлів, namespace та додаткові аргументи.
-runConftestBatch: Запускає `conftest test` для заданого списку файлів, повертає масив порушень у форматі JSON, якщо `conftest` успішно завершився, і кидає виняток, якщо `conftest` не знайдено або завершився з помилкою. Створює тимчасову директорію для збереження даних шаблону, якщо передано `templateData`.
+runConftestBatch: Асинхронно запускає `conftest test` для заданого списку файлів, повертає `Promise` з масивом порушень у форматі JSON, якщо `conftest` успішно завершився, і кидає виняток (реджектить), якщо `conftest` не знайдено або завершився з помилкою (включно з `null` exit-кодом — процес вбито через `timeoutMs`/`signal`). Створює тимчасову директорію для збереження даних шаблону, якщо передано `templateData`.
 
 ## Публічний API
 
 - buildConftestArgs: Створює аргументи для тесту conftest. Витягнуто для зручності тестування. Зберігає поточну структуру аргументів (файли перед `-p`, `--output json` та `--no-color` для читабельного виводу) і вставляє `--data` після `--namespace`, якщо він заданий.
-- runConftestBatch: Запускає `conftest test` для всіх файлів з одного процесу та повертає масив помилок. Якщо `files` порожній, повертає порожній масив. Якщо `conftest` не знайдено в системному шляху та автоматична установка не вдалася, виникає помилка.
+- runConftestBatch: Асинхронно запускає `conftest test` для всіх файлів з одного процесу та повертає `Promise` з масивом помилок. Якщо `files` порожній, резолвиться порожнім масивом без спавну. Якщо `conftest` не знайдено в системному шляху та автоматична установка не вдалася, `Promise` реджектиться.
 
 ## Гарантії поведінки