@7n/rules 1.13.1 → 1.14.1

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## [1.14.1] - 2026-07-18
+
+### Changed
+
+- docs(adr): brainstorm — внутрішній паралелізм lint-оркестратора (#86)
+- Оновлено внутрішній lint-оркестратор.
+
+## [1.14.0] - 2026-07-18
+
+### Changed
+
+- js/eslint: fix-worker.mjs — обмежений паралельний пул (MAX_PARALLEL_FILES=4) замість послідовного циклу по файлах; профайлінг спростував гіпотезу про bootstrap-накладні витрати сесії
+
 ## [1.13.1] - 2026-07-18
 
 ### Changed

package/package.json

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

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/fix-worker.md

@@ -3,21 +3,21 @@ type: JS Module
 title: fix-worker.mjs
 resource: npm/rules/js/eslint/fix-worker.mjs
 docgen:
-  crc: 1eb9c7fc
+  crc: 802ef1f3
   model: manual
 ---
 
 ## Огляд
 
-Custom fix-worker `js/eslint` (перекриває дефолтний `default-worker.mjs`): замість одного `runAgentFix`-виклику з усіма порушеннями з усіх файлів concern-а — окрема агентна сесія на кожен файл, у межах спільного дедлайну rung-а. Мотивація — виміряно на реальних lint-прогонах: одна сесія, що жонглює кількома файлами одразу, стабільно впирається у timeout на всіх 4 rung-ах драбини (local-min→cloud-avg), навіть при малому обсязі порушень; та сама модель, scoped на один файл, укладається в бюджет і закриває більшість порушень.
+Custom fix-worker `js/eslint` (перекриває дефолтний `default-worker.mjs`): замість одного `runAgentFix`-виклику з усіма порушеннями з усіх файлів concern-а — окрема агентна сесія на кожен файл, ПАРАЛЕЛЬНО (обмежений пул, не більше `MAX_PARALLEL_FILES`). Мотивація й еволюція дизайну — `docs/adr/260718-0754-js-eslint-fix-worker-per-session-overhead.md`: послідовна версія стабільно впиралась у timeout на всіх 4 rung-ах драбини (local-min→cloud-avg); профайлінг реального прогону показав, що домінує кількість/довжина раундів моделі на файл, а не фіксовані bootstrap-витрати сесії — тож паралелізм (кілька файлів одночасно замість черги) дає пряме пришвидшення незалежно від причини.
 
 ## Поведінка
 
 1. Групує вхідні `violations` за `file`; порушення без `file` ігноруються.
-2. Дедлайн — `DEADLINE_FRACTION` (0.8) від `ctx.timeoutMs`; цикл перевіряє дедлайн ПЕРЕД стартом кожного файлу і не починає новий, якщо час вичерпано.
-3. Кожен файл отримує РЕШТУ бюджету до дедлайну (не фіксований поділ `timeoutMs / files.length`) — перший (часто найважчий) файл отримує найбільше часу.
+2. Дедлайн — `DEADLINE_FRACTION` (0.8) від `ctx.timeoutMs`; гейтить лише СТАРТ нового файлу з черги (не скасовує вже запущені).
+3. `runPooled` — обмежений пул воркерів (`MAX_PARALLEL_FILES=4`): при `files.length ≤ MAX_PARALLEL_FILES` усі файли стартують майже одночасно й отримують практично весь бюджет незалежно один від одного; при більшій кількості черга природно звужує бюджет пізніших хвиль (`callTimeoutMs` рахується в момент старту файлу з черги, не наперед).
 4. На кожен файл — окремий `runAgentFix` із `targetFiles: [file]` і власним `verify` (`verifyFile`): item-scoped canonical re-detect лише цього файлу, не всього concern-а — інакше evidence-гейт хибно вважав би файл незакритим через порушення в ІНШИХ файлах.
-5. Один файл, що завершився з `error`, не обриває цикл — пропускається, наступні файли все одно обробляються в межах дедлайну.
+5. Один файл, що завершився з `error` АБО кинув виняток (try/catch у тілі воркера), не обриває пул — пропускається, решта файлів обробляються незалежно.
 6. Повертає лише `touchedFiles` з успішних (`!error`) викликів; success rung-а все одно визначає whole-concern canonical re-detect runner-а (`runRung`), не цей worker.
 
 ## Публічний API
@@ -28,3 +28,4 @@ Custom fix-worker `js/eslint` (перекриває дефолтний `default-
 
 - Пише лише у файли з переданих `violations` (`targetFiles: [file]` на кожен виклик) — той самий semantic-collateral guard, що й у дефолтного worker-а.
 - `recordWrite` (не durable) на кожен файл: rollback-контракт незмінний — якщо після worker-а в concern-і лишилось хоч одне порушення будь-де, `runRung` відкочує ВСІ правки цього rung-а, включно з уже полагодженими файлами.
+- Конкурентні виклики `recordWrite` безпечні: central snapshot — синхронні Map-операції без `await` усередині, event loop не перериває їх посеред виконання.

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/fix-worker.mjs

@@ -4,22 +4,33 @@
  * з УСІХ файлів в один `runAgentFix`-виклик — на реальних lint-прогонах (tauri-components)
  * це давало 100% timeout на всіх 4 rung-ах драбини (local-min→cloud-avg), навіть коли
  * порушень було лише 20-90 у 1-3 файлах: одна сесія жонглює кількома файлами одразу і не
- * встигає в rung-таймаут. Виміряно (2026-07-17, ручний timing-експеримент поза pipeline):
- * одна сесія, scoped на ОДИН найважчий файл (21 порушення), закрила 76% (16/21) за 91с із
- * бюджету 120с (cloud-min) — per-file scoping вкладається, mega-prompt — ні.
+ * встигає в rung-таймаут.
+ *
+ * Файли обробляються ПАРАЛЕЛЬНО (обмежений пул, `MAX_PARALLEL_FILES`), не послідовно —
+ * ADR docs/adr/260718-0754-js-eslint-fix-worker-per-session-overhead.md. Профайлінг
+ * реального прогону (2026-07-18, trace `runAgentFix`) спростував гіпотезу про фіксовані
+ * bootstrap-витрати сесії: `dispatch.test.js` (2 порушення) — 9 раундів моделі, 29.4с;
+ * тривіальний фікс так само вимагав багато tool-раундів, а не одноразової плати за bootstrap.
+ * Оскільки домінує саме кількість/довжина turn-раундів, а не старт сесії, паралелізм
+ * (кілька файлів одночасно замість черги) дає пряме пришвидшення незалежно від причини —
+ * секвенційна версія витрачала весь бюджет rung-а на 1 файл, лишаючи іншим 0 шансів
+ * навіть стартувати.
  *
  * Rollback-контракт незмінний: `recordWrite` (не durable) на кожен файл — правки наявного
  * стороннього коду. Якщо після worker-а `runRung`-ів canonical re-detect (whole-concern)
  * знайде хоч одне порушення будь-де, увесь rung однаково відкотиться (S1) — той самий
- * контракт, що й у дефолтного worker-а; батчинг підвищує ймовірність, що ЦЕЙ rung дійде
- * до 0 порушень, а не замінює rollback-семантику.
+ * контракт, що й у дефолтного worker-а; паралелізм підвищує ймовірність, що ЦЕЙ rung
+ * дійде до 0 порушень, а не замінює rollback-семантику. `snapshot.record`/`recordWrite` —
+ * синхронні Map-операції без `await` усередині, тож конкурентні виклики безпечні (Node
+ * event loop не перериває синхронний блок).
  *
  * Дедлайн (`DEADLINE_FRACTION` від `ctx.timeoutMs`, той самий підхід, що й
- * `doc-files/check/fix-worker.mjs`): цикл не стартує наступний файл, якщо дедлайн
- * настав — worker повертає часткову роботу штатно, замість фонової сесії, що триває
- * поверх backstop ×1.25 runner-а. Кожен файл отримує РЕШТУ бюджету до дедлайну (не
- * фіксований `timeoutMs / files.length`) — перший (часто найважчий) файл отримує
- * найбільше часу, а не штучно урізаний рівний шматок.
+ * `doc-files/check/fix-worker.mjs`) гейтить лише СТАРТ нового файлу з черги — не
+ * скасовує вже запущені. При files.length ≤ MAX_PARALLEL_FILES усі стартують майже
+ * одночасно й отримують практично весь бюджет незалежно один від одного (справжній
+ * паралелізм); при більшій кількості — черга природно звужує бюджет пізніших хвиль
+ * (`callTimeoutMs` рахується в момент старту, не наперед), не даючи перевищити
+ * backstop ×1.25 runner-а.
  * @typedef {import('../../../scripts/lib/lint-surface/types.mjs').FixWorkerFn} FixWorkerFn
  */
 import { resolve } from 'node:path'
@@ -28,9 +39,12 @@ import { anchoredEnabled } from '../../../scripts/lib/lint-surface/default-worke
 import { renderViolations } from '../../../scripts/lib/lint-surface/render.mjs'
 import { lint } from './main.mjs'
 
-/** Частка ctx.timeoutMs, після якої цикл не стартує наступний файл (запас до backstop ×1.25). */
+/** Частка ctx.timeoutMs, після якої черга не стартує новий файл (запас до backstop ×1.25). */
 const DEADLINE_FRACTION = 0.8
 
+/** Максимум файлів, що обробляються одночасно (без необмеженого burst на великих concern-ах). */
+const MAX_PARALLEL_FILES = 4
+
 /**
  * Item-scoped (один файл) canonical re-detect для evidence-гейта `runAgentFix` —
  * НЕ те саме, що whole-concern `ctx.verify` з `runRung` (той перевірив би ВСІ файли
@@ -47,6 +61,27 @@ async function verifyFile(cwd, ruleId, concernId, file) {
   return { ok: stamped.length === 0, output: renderViolations(stamped) }
 }
 
+/**
+ * Обробляє `items` обмеженим пулом воркерів (не більше `MAX_PARALLEL_FILES` одночасно) —
+ * власна черга замість `Promise.all(items.map(...))`, щоб великий concern не відкрив
+ * необмежену кількість конкурентних агентних сесій одразу.
+ * @param {string[]} items елементи черги (шляхи файлів)
+ * @param {(item: string) => Promise<void>} worker обробник одного елемента; винятки ловить сам
+ * @returns {Promise<void>}
+ */
+async function runPooled(items, worker) {
+  const queue = [...items]
+  const runnerCount = Math.min(MAX_PARALLEL_FILES, items.length)
+  await Promise.all(
+    Array.from({ length: runnerCount }, async () => {
+      let item
+      while ((item = queue.shift())) {
+        await worker(item)
+      }
+    })
+  )
+}
+
 /** @type {FixWorkerFn} */
 export async function fixWorker(violations, ctx) {
   // lazy import — тримає detect-шлях вільним від pi/oxc (read-only --no-fix не вантажить їх).
@@ -71,29 +106,34 @@ export async function fixWorker(violations, ctx) {
   const anchoredEdits = anchoredEnabled(ctx.model, isLocalModel)
 
   const touchedFiles = []
-  for (const file of files) {
-    if (deadlineAt && Date.now() >= deadlineAt) break
+  await runPooled(files, async file => {
+    if (deadlineAt && Date.now() >= deadlineAt) return
     const callTimeoutMs = deadlineAt ? Math.max(1000, deadlineAt - Date.now()) : ctx.timeoutMs
 
-    const res = await runAgentFix(ctx.ruleId, renderViolations(byFile.get(file)), ctx.cwd, {
-      model: ctx.model,
-      tier: ctx.tier,
-      timeoutMs: callTimeoutMs,
-      feedback: ctx.feedback ?? null,
-      caller: `fix:${ctx.ruleId}/${ctx.concernId}:${ctx.tier}:${file}`,
-      recordWrite: ctx.recordWrite,
-      chain: ctx.chain ?? null,
-      targetFiles: [file],
-      verify: () => verifyFile(ctx.cwd, ctx.ruleId, ctx.concernId, file),
-      verifyMax: ctx.verifyMax,
-      anchoredEdits,
-      deps: { astContext: p => extractContext(resolve(ctx.cwd, p)) }
-    })
+    let res
+    try {
+      res = await runAgentFix(ctx.ruleId, renderViolations(byFile.get(file)), ctx.cwd, {
+        model: ctx.model,
+        tier: ctx.tier,
+        timeoutMs: callTimeoutMs,
+        feedback: ctx.feedback ?? null,
+        caller: `fix:${ctx.ruleId}/${ctx.concernId}:${ctx.tier}:${file}`,
+        recordWrite: ctx.recordWrite,
+        chain: ctx.chain ?? null,
+        targetFiles: [file],
+        verify: () => verifyFile(ctx.cwd, ctx.ruleId, ctx.concernId, file),
+        verifyMax: ctx.verifyMax,
+        anchoredEdits,
+        deps: { astContext: p => extractContext(resolve(ctx.cwd, p)) }
+      })
+    } catch {
+      // Один файл впав винятком — не валимо решту паралельних воркерів у пулі; whole-concern
+      // canonical re-detect runner-а (не цей worker) визначить, чи rung закрито.
+      return
+    }
 
-    // Один файл не впорався — не кидаємо, пробуємо решту в межах дедлайну; whole-concern
-    // canonical re-detect runner-а (не цей worker) визначить, чи rung закрито.
     if (!res.error) touchedFiles.push(...(res.touchedFiles ?? []))
-  }
+  })
 
   return { touchedFiles }
 }

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/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` реджектиться.
 
 ## Гарантії поведінки