@7n/rules 1.14.0 → 1.14.1

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [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.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/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/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` реджектиться.
 
 ## Гарантії поведінки
 

package/scripts/lib/ensure-tool.mjs

@@ -6,16 +6,24 @@
  *
  * Per-platform matrix: macOS → brew, Windows → scoop (fallback: GitHub Release), Linux → GitHub Release binary.
  * Бінарники кешуються у `~/.cache/@7n/rules/bin/` (Linux/Mac), `%LOCALAPPDATA%\@7n\cursor\bin\` (Win).
+ * Download завжди пишеться в унікальний per-call temp-каталог і публікується атомарним `renameSync` —
+ * паралельні install того самого тула (різні процеси/промиси) не тупцюють по спільному archive-шляху.
+ *
+ * `ensureTool` лишається синхронним — публічний API пакету (`@7n/rules/scripts/lib/ensure-tool.mjs`,
+ * реально споживається зовнішнім `plugins/ci-github`), сигнатуру не міняємо. `ensureToolAsync(toolId)` —
+ * async-варіант для parallel lane `detectAll()`: внутрішньопроцесний single-flight + міжпроцесний
+ * `withLock` навколо auto-install кроку (`docs/adr/260716-1354-…`).
  *
  * `ensureHkInstall(hkBin)` — реєструє git pre-commit hook через `hk install`; пропускається в CI.
  */
 import { spawnSync } from 'node:child_process'
-import { chmodSync, existsSync, mkdirSync, renameSync } from 'node:fs'
+import { chmodSync, existsSync, mkdirSync, mkdtempSync, renameSync, rmSync } from 'node:fs'
 import { homedir } from 'node:os'
 import { join } from 'node:path'
 import { arch, env, platform } from 'node:process'
 
 import { resolveCmd } from '../utils/resolve-cmd.mjs'
+import { withLock } from '../utils/with-lock.mjs'
 
 /** Префікс `v` у git-тегу релізу (`v1.2.3` → `1.2.3`). */
 const TAG_V_PREFIX_RE = /^v/
@@ -189,39 +197,53 @@ function installFromGithub(toolId, entry, cacheDir) {
   const downloadUrl = `https://github.com/${entry.github}/releases/download/v${ver}/${assetName}`
 
   mkdirSync(cacheDir, { recursive: true })
-  const archivePath = join(cacheDir, assetName)
-
-  const dlResult = spawnSync(curlBin, ['-sSL', '-o', archivePath, downloadUrl], { encoding: 'utf8' })
-  if (dlResult.error) throw new Error(`Завантаження ${toolId} не вдалось: ${dlResult.error.message}`)
-  if (dlResult.status !== 0)
-    throw new Error(`curl exit ${dlResult.status} при завантаженні ${toolId}: ${(dlResult.stderr ?? '').slice(0, 300)}`)
-
-  // Сирий бінарник (archive: false) — завантажений файл і є бінарником: перейменовуємо у <toolId> + chmod.
-  if (entry.archive === false) {
-    const binPath = join(cacheDir, toolId)
-    renameSync(archivePath, binPath)
-    chmodSync(binPath, 0o755)
-    return binPath
-  }
+  // Унікальний per-call temp-каталог у тому ж cacheDir (той самий filesystem — атомарний renameSync
+  // наприкінці не впаде з EXDEV). Паралельні install-и того самого тула пишуть у різні temp-каталоги,
+  // не конфліктуючи один з одним; під фіксованим `<toolId>`-іменем публікується лише готовий бінарник.
+  const tmpDir = mkdtempSync(join(cacheDir, `.tmp-${toolId}-`))
+  try {
+    const archivePath = join(tmpDir, assetName)
 
-  // .tar.xz потребує -J замість -z
-  const isXz = assetName.endsWith('.tar.xz')
-  const tarFlags = isXz ? ['-xJf'] : ['-xzf']
-  const extractResult = spawnSync(tarBin, [...tarFlags, archivePath, '-C', cacheDir], { encoding: 'utf8' })
-  if (extractResult.error) throw new Error(`tar failed for ${toolId}: ${extractResult.error.message}`)
-  if (extractResult.status !== 0)
-    throw new Error(`tar exit ${extractResult.status} для ${toolId}: ${(extractResult.stderr ?? '').slice(0, 300)}`)
-
-  const binRelPath = entry.binFinder ? entry.binFinder(ver) : toolId
-  const binPath = join(cacheDir, binRelPath)
-  if (!existsSync(binPath)) {
-    throw new Error(`Бінарник ${toolId} не знайдено після розпакування: ${binPath}`)
-  }
+    const dlResult = spawnSync(curlBin, ['-sSL', '-o', archivePath, downloadUrl], { encoding: 'utf8' })
+    if (dlResult.error) throw new Error(`Завантаження ${toolId} не вдалось: ${dlResult.error.message}`)
+    if (dlResult.status !== 0) {
+      throw new Error(
+        `curl exit ${dlResult.status} при завантаженні ${toolId}: ${(dlResult.stderr ?? '').slice(0, 300)}`
+      )
+    }
+
+    const publishedBin = join(cacheDir, toolId)
+
+    // Сирий бінарник (archive: false) — завантажений файл і є бінарником: chmod + атомарна публікація.
+    if (entry.archive === false) {
+      chmodSync(archivePath, 0o755)
+      renameSync(archivePath, publishedBin)
+      return publishedBin
+    }
+
+    // .tar.xz потребує -J замість -z
+    const isXz = assetName.endsWith('.tar.xz')
+    const tarFlags = isXz ? ['-xJf'] : ['-xzf']
+    const extractResult = spawnSync(tarBin, [...tarFlags, archivePath, '-C', tmpDir], { encoding: 'utf8' })
+    if (extractResult.error) throw new Error(`tar failed for ${toolId}: ${extractResult.error.message}`)
+    if (extractResult.status !== 0) {
+      throw new Error(`tar exit ${extractResult.status} для ${toolId}: ${(extractResult.stderr ?? '').slice(0, 300)}`)
+    }
 
-  const rmBin = resolveCmd('rm')
-  if (rmBin) spawnSync(rmBin, [archivePath])
+    const binRelPath = entry.binFinder ? entry.binFinder(ver) : toolId
+    const extractedBin = join(tmpDir, binRelPath)
+    if (!existsSync(extractedBin)) {
+      throw new Error(`Бінарник ${toolId} не знайдено після розпакування: ${extractedBin}`)
+    }
 
-  return binPath
+    // Атомарна публікація під фіксованим flat-іменем — незалежно від вкладеної структури архіву
+    // (напр. shellcheck розпаковується у `shellcheck-v<ver>/shellcheck`), щоб наступний виклик
+    // `ensureTool` бачив кеш за тим самим шляхом, яким його перевіряє (`join(cacheDir, toolId)`).
+    renameSync(extractedBin, publishedBin)
+    return publishedBin
+  } finally {
+    rmSync(tmpDir, { recursive: true, force: true })
+  }
 }
 
 /**
@@ -334,6 +356,78 @@ export function ensureTool(toolId) {
   throw new Error(buildHint(toolId, entry))
 }
 
+/** Внутрішньопроцесний single-flight: конкурентні `ensureToolAsync(toolId)` в одному Node-процесі колапсують в один install. */
+const inFlightInstalls = new Map()
+
+/**
+ * Обгортає `autoInstall` міжпроцесним `withLock` — паралельні Node-процеси (різні CI-shard-и,
+ * кілька агентів на тій самій машині) чекають у черзі замість конкурентного запису в спільний
+ * cache/archive-шлях. Fingerprint-дедуп локу вимкнено (`getFingerprint: () => null`) — той
+ * механізм призначений для повторних CLI-команд на тому самому git-дереві, тут важлива лише
+ * взаємовиключність; після взяття локу перевіряємо кеш повторно (інший процес міг встановити,
+ * поки ми чекали).
+ * @param {string} toolId ключ у реєстрі TOOLS
+ * @param {ToolEntry} entry опис тула
+ * @param {string} cacheDir каталог кешу
+ * @returns {Promise<string>} абсолютний шлях до бінарника
+ */
+async function installWithCrossProcessLock(toolId, entry, cacheDir) {
+  let resultPath = null
+  await withLock(
+    `ensure-tool/${toolId}`,
+    () => {
+      const cachedBin = join(cacheDir, toolId)
+      resultPath = existsSync(cachedBin) ? cachedBin : autoInstall(toolId, entry, cacheDir)
+      return 0
+    },
+    { onWaitTimeout: 'fail', getFingerprint: () => null }
+  )
+  return resultPath
+}
+
+/**
+ * Async-варіант `ensureTool` для parallel lane `detectAll()` (ADR 260716-1354). `ensureTool`
+ * (sync) лишається незміненою — публічний API пакета; ця функція існує окремо, не заміняє її.
+ *
+ * Fast-paths (PATH, уже закешований бінарник) — ідентичні sync-версії. Auto-install — єдина
+ * гілка, що реально потребує async: обгорнута internal single-flight (`inFlightInstalls`) і
+ * cross-process `withLock`, щоб паралельні виклики того самого `toolId` (в одному процесі чи
+ * кількох) не тягнули install конкурентно.
+ * @param {string} toolId ключ у реєстрі TOOLS (`'hk'`, `'conftest'`, `'shellcheck'`, `'actionlint'`, `'dotenv-linter'`, `'opa'`, `'regal'`, `'hadolint'`, `'kubeconform'`, `'kubescape'`)
+ * @returns {Promise<string>} абсолютний шлях до бінарника
+ */
+export async function ensureToolAsync(toolId) {
+  const entry = TOOLS[toolId]
+  if (!entry) throw new Error(`ensureTool: невідомий тул '${toolId}'`)
+
+  // 1. PATH
+  const fromPath = resolveCmd(toolId)
+  if (fromPath) return fromPath
+
+  // 2. Кеш
+  const cacheDir = getCacheDir()
+  const cachedBin = join(cacheDir, toolId)
+  if (existsSync(cachedBin)) return cachedBin
+
+  // 3. Hard-fail (opt-out) — до single-flight, щоб не ставити зайвий запис у Map даремно
+  if (env['N_CURSOR_NO_AUTO_INSTALL']) throw new Error(buildHint(toolId, entry))
+
+  // 4. Авто-install: single-flight (in-process) + withLock (cross-process)
+  const inFlight = inFlightInstalls.get(toolId)
+  if (inFlight) return inFlight
+
+  const installPromise = installWithCrossProcessLock(toolId, entry, cacheDir)
+  inFlightInstalls.set(toolId, installPromise)
+  try {
+    // Єдиний реальний await у функції: коли installPromise усталиться (для ЦЬОГО, ініціюючого
+    // виклику — конкурентні виклики вище просто повернули той самий inFlight), приберемо запис
+    // з Map рівно один раз, незалежно від того, скільки викликів чекало на той самий проміс.
+    return await installPromise
+  } finally {
+    inFlightInstalls.delete(toolId)
+  }
+}
+
 /**
  * Реєструє git pre-commit hook через `hk install`.
  * Пропускається в CI (`process.env.CI`). Попереджає (не кидає) на помилку.