@7n/rules 1.13.1 → 1.14.1

package/scripts/lib/lint-surface/scheduler.mjs

@@ -0,0 +1,96 @@
+/**
+ * Bounded two-lane concurrent scheduler для `detectAll()` (ADR 260716-1354). Активний лише
+ * коли `concurrency > 1` (деталі — `run-detectors.mjs`); за замовчуванням (`concurrency === 1`)
+ * `detectAll` лишається на повністю послідовному шляху, спостережувано ідентичному до-ADR
+ * поведінці — ця функція там навіть не викликається.
+ *
+ * Два лейни за `isSerial(item)`: **serial lane** — власний sequential runner (mutex за
+ * конструкцією, items ніколи не перекриваються самі з собою); **parallel lane** — bounded
+ * pool до `concurrency` слотів. Обидва лейни виконуються конкурентно один з одним — свідомий
+ * вибір: serial-lane item, коли реально виконує свій blocking `spawnSync`, все одно заморожує
+ * весь event loop (тобто "конкурентність" із parallel lane суто структурна, не робить
+ * serial-lane item швидшим), а parallel-lane пул отримує реальну вигоду від одночасного
+ * очікування кількох `spawnAsync`-викликів.
+ *
+ * Перший виняток від `runItem` зупиняє нові старти в обох лейнах, `controller.abort()`
+ * сигналізує вже запущеним async-детекторам, і функція чекає завершення всіх уже
+ * стартованих items (кожен `runOne` сам ловить власну помилку — жоден виклик не відхиляє
+ * зовнішній `Promise.all`) перед поверненням.
+ */
+
+/**
+ * @template T, R
+ * @typedef {object} PlanItemOutcome
+ * @property {T} item вхідний item
+ * @property {R} [result] результат `runItem`, якщо завершився успішно
+ * @property {unknown} [error] помилка `runItem` (перша — стає `infraError`)
+ * @property {boolean} [aborted] true — item отримав `AbortError` уже ПІСЛЯ того, як інший item
+ *   зупинив плановий прогін (очікуване скасування, не нова інфра-помилка)
+ */
+
+/**
+ * @template T, R
+ * @param {T[]} items вхідний план (в оригінальному порядку)
+ * @param {object} opts опції планування
+ * @param {number} opts.concurrency bounded pool розмір для parallel lane (мінімум 1)
+ * @param {(item: T) => boolean} opts.isSerial чи item належить serial lane
+ * @param {(item: T, signal: AbortSignal) => Promise<R>} opts.runItem виконує один item;
+ *   кидання зупиняє планування нових items і абортить `signal`
+ * @returns {Promise<{ results: PlanItemOutcome<T, R>[], infraError: unknown|null }>}
+ *   `results` — лише items, що реально стартували (в порядку завершення, не вхідному);
+ *   `infraError` — перша помилка `runItem`, або `null`, якщо всі items завершились успішно
+ */
+export async function runPlanConcurrently(items, { concurrency, isSerial, runItem }) {
+  const controller = new AbortController()
+  const parallelItems = []
+  const serialItems = []
+  for (const item of items) (isSerial(item) ? serialItems : parallelItems).push(item)
+
+  /** @type {PlanItemOutcome<T, R>[]} */
+  const results = []
+  let infraError = null
+  let stopped = false
+
+  const runOne = async item => {
+    if (stopped) return
+    try {
+      const result = await runItem(item, controller.signal)
+      results.push({ item, result })
+    } catch (error) {
+      if (stopped && error?.name === 'AbortError') {
+        results.push({ item, aborted: true })
+        return
+      }
+      results.push({ item, error })
+      if (!stopped) {
+        stopped = true
+        infraError = error
+        controller.abort()
+      }
+    }
+  }
+
+  const runSerialLane = async () => {
+    for (const item of serialItems) {
+      if (stopped) break
+      await runOne(item)
+    }
+  }
+
+  const runParallelLane = async () => {
+    let next = 0
+    const worker = async () => {
+      while (!stopped) {
+        const i = next++
+        if (i >= parallelItems.length) return
+        await runOne(parallelItems[i])
+      }
+    }
+    const workerCount = Math.min(concurrency, parallelItems.length)
+    await Promise.all(Array.from({ length: workerCount }, worker))
+  }
+
+  await Promise.all([runSerialLane(), runParallelLane()])
+
+  return { results, infraError }
+}

package/scripts/lib/lint-surface/types.mjs

@@ -21,6 +21,9 @@
  *   `undefined` означає whole-repo
  * @property {boolean} [verbose] `--verbose` CLI-прапорець; concern-и із зовнішніми
  *   інструментами (напр. `ga/workflows`) звіряються з ним, щоб не засмічувати прогрес-бар `lint --full`
+ * @property {AbortSignal} [signal] сигнал скасування — лише у parallel lane `detectAll()`
+ *   (`N_RULES_LINT_CONCURRENCY>1`, ADR 260716-1354); async-детектори (`spawnAsync`-based)
+ *   прокидають його далі, щоб перерватись при infrastructure-помилці іншого concern-а
  */
 
 /**

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

@@ -9,16 +9,20 @@
  * ризик дрифту (типу `spec.config` vs `spec.default.config` у
  * `health_check_policy.rego`, що ми ловили cross-check тестами).
  *
- * Hard-fail на відсутність `conftest` — через `ensureTool`, що спочатку
+ * Hard-fail на відсутність `conftest` — через `ensureToolAsync`, що спочатку
  * намагається авто-встановити, і лише після невдачі кидає виняток.
+ *
+ * Async (`spawnAsync`, не `spawnSync`) — детектор не блокує event loop, тож може
+ * виконуватись у parallel lane `detectAll()` (ADR 260716-1354). Приймає опційний
+ * `signal`/`timeoutMs` — прокидаються в `spawnAsync`.
  */
-import { spawnSync } from 'node:child_process'
 import { existsSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import { dirname, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
-import { ensureTool } from './ensure-tool.mjs'
+import { ensureToolAsync } from './ensure-tool.mjs'
+import { spawnAsync } from '../utils/spawn-async.mjs'
 
 /**
   Каталог пакета `@7n/rules`, від якого ресолвимо вшиті директорії правил.
@@ -44,6 +48,8 @@ const RULES_ROOT = join(PACKAGE_ROOT, 'rules')
  * @property {string[]} files список абсолютних шляхів файлів для перевірки (порожній — повертаємо порожньо)
  * @property {string[]} [extraArgs] додаткові аргументи для conftest (наприклад `--combine` для крос-документних правил)
  * @property {object} [templateData] опціональне merged-дерево; серіалізується у JSON `{ "template": <data> }` і передається як `--data <tmpfile>` (cleanup після завершення)
+ * @property {AbortSignal} [signal] сигнал скасування — прокидається у `spawnAsync`
+ * @property {number} [timeoutMs] ліміт виконання `conftest` у мілісекундах — прокидається у `spawnAsync`
  */
 
 /**
@@ -65,11 +71,11 @@ export function buildConftestArgs(p) {
  * порушень. Якщо `files` порожній — повертає `[]` без спавна. Якщо `conftest`
  * не у PATH і авто-встановлення не вдалось — кидає виняток (hard fail).
  * @param {ConftestBatchOptions} opts параметри запуску
- * @returns {ConftestViolation[]} масив порушень (порожній — все ок)
+ * @returns {Promise<ConftestViolation[]>} масив порушень (порожній — все ок)
  */
-export function runConftestBatch(opts) {
+export async function runConftestBatch(opts) {
   if (opts.files.length === 0) return []
-  const conftestBin = ensureTool('conftest')
+  const conftestBin = await ensureToolAsync('conftest')
   // policyDirRel — формат `<rule>/<concern>` (наприклад `abie/base_deployment_preem`).
   // Flat concern path: rules/<rule>/<concern>/ (без проміжного `policy/`).
   const slash = opts.policyDirRel.indexOf('/')
@@ -94,11 +100,10 @@ export function runConftestBatch(opts) {
       extraArgs: opts.extraArgs ?? [],
       tmpDataFile
     })
-    const result = spawnSync(conftestBin, args, { encoding: 'utf8' })
-    if (result.error) throw result.error
-    // conftest exit 1 = є failures (це валідно для нас); >1 = справжня помилка.
-    if (result.status !== 0 && result.status !== 1) {
-      throw new Error(`conftest exit ${result.status}: ${(result.stderr || result.stdout || '').slice(0, 500)}`)
+    const result = await spawnAsync(conftestBin, args, { signal: opts.signal, timeoutMs: opts.timeoutMs })
+    // conftest exit 1 = є failures (це валідно для нас); >1 (або null — вбито сигналом/таймаутом) = справжня помилка.
+    if (result.exitCode !== 0 && result.exitCode !== 1) {
+      throw new Error(`conftest exit ${result.exitCode}: ${(result.stderr || result.stdout || '').slice(0, 500)}`)
     }
     /**
   @type {Array<{ filename: string, namespace: string, failures?: Array<{ msg: string }> }>}

package/scripts/utils/docs/index.md

@@ -16,6 +16,7 @@ resource: npm/scripts/utils/
 | [resolve-cargo-manifest.mjs](resolve-cargo-manifest.md)     | JS Module |
 | [resolve-cmd.mjs](resolve-cmd.md)                           | JS Module |
 | [resolve-js-root.mjs](resolve-js-root.md)                   | JS Module |
+| [spawn-async.mjs](spawn-async.md)                           | JS Module |
 | [test-helpers.mjs](test-helpers.md)                         | JS Module |
 | [walk-cache.mjs](walk-cache.md)                             | JS Module |
 | [walkDir.mjs](walkDir.md)                                   | JS Module |

package/scripts/utils/docs/spawn-async.md

@@ -0,0 +1,33 @@
+---
+type: JS Module
+title: spawn-async.mjs
+resource: npm/scripts/utils/spawn-async.mjs
+docgen:
+  crc: cc5d92e0
+  model: openai-codex/gpt-5.4-mini
+  tier: cloud-min
+  score: 100
+  issues: judge:inaccurate:0.98
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+## Огляд
+
+Забезпечує асинхронну заміну `spawnSync` для важких зовнішніх CLI на кшталт `conftest` і `oxlint`, щоб не блокувати Node event loop і не створювати ілюзію паралельності під час запуску кількох detector’ів. Обгортає `child_process.spawn` через `events.once`, підтримує зовнішній `AbortSignal` і `timeoutMs` з ескалацією `SIGTERM` → `SIGKILL`, а результат повертає нормалізовано без винятку на non-zero exit — рішення про це лишається за caller.
+
+## Поведінка
+
+1. `spawnAsync` запускає зовнішній CLI асинхронно, щоб не блокувати event loop під час важких системних перевірок.
+2. Якщо запуск уже скасовано до старту, одразу повертає помилку скасування.
+3. Збирає `stdout` і `stderr` у нормалізований текстовий результат для подальшого аналізу викликачем.
+4. Підтримує зовнішнє скасування та часовий ліміт: у цих випадках спершу намагається завершити процес м’яко, а потім примусово, якщо він не зупинився в межах grace-періоду.
+5. Повертає код завершення, сигнал завершення та ознаки скасування або timeout як звичайний результат, а не як виняток.
+6. Кидає помилку лише тоді, коли сам запуск процесу не відбувся або середовище не змогло стартувати команду; non-zero exit лишається відповідальністю викликачa.
+
+## Публічний API
+
+- spawnAsync — асинхронно запускає зовнішню команду, дочікується завершення, збирає її вихід і повертає результат; не падає через code ≠ 0, а кидає лише коли процес не вдалося створити або якщо сигнал уже був aborted до старту
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).

package/scripts/utils/spawn-async.mjs

@@ -0,0 +1,112 @@
+/**
+ * Async (non-blocking) заміна `spawnSync` для важких зовнішніх CLI-викликів (conftest, oxlint тощо).
+ *
+ * `spawnSync` блокує весь Node event loop цілком — паралельний виклик кількох
+ * concern-детекторів навколо `spawnSync` не дає реальної паралельності, лише ілюзію.
+ * `spawnAsync` обгортає `child_process.spawn` через `events.once` (без `new Promise`,
+ * `promise/avoid-new` заборонений у цьому пакеті), підтримує зовнішній `AbortSignal`
+ * і `timeoutMs` (обидва ведуть до `SIGTERM` → ескалація `SIGKILL`, якщо процес не
+ * завершився за grace-період), і повертає нормалізований результат без винятку на
+ * non-zero exit — це, як і раніше, вирішує caller.
+ */
+import { spawn } from 'node:child_process'
+import { once } from 'node:events'
+
+/**
+ * @typedef {object} SpawnAsyncResult
+ * @property {string} stdout зібраний stdout (utf8)
+ * @property {string} stderr зібраний stderr (utf8)
+ * @property {number|null} exitCode код завершення (`null` — процес вбито сигналом)
+ * @property {string|null} signal сигнал, яким вбито процес (`null` — завершився сам)
+ * @property {boolean} timedOut true, якщо процес вбито через `timeoutMs`
+ * @property {boolean} aborted true, якщо процес вбито через зовнішній `AbortSignal`
+ */
+
+/** `AbortError` (DOM `AbortController` семантика) для вже-скасованого `signal` до старту спавна. */
+class AbortError extends Error {
+  /** @param {string} [message] текст помилки */
+  constructor(message = 'The operation was aborted') {
+    super(message)
+    this.name = 'AbortError'
+  }
+}
+
+/**
+ * Запускає зовнішній процес асинхронно (не блокує event loop) і збирає його результат.
+ * Ніколи не кидає на non-zero exit — кидає лише на `spawn`-помилку (ENOENT тощо) або
+ * якщо `opts.signal` вже `aborted` до виклику.
+ * @param {string} cmd бінарник (шлях або ім'я в PATH)
+ * @param {string[]} args аргументи запуску
+ * @param {object} [opts] опції
+ * @param {AbortSignal} [opts.signal] зовнішній сигнал скасування
+ * @param {number} [opts.timeoutMs] ліміт у мілісекундах (без ліміту — не задано / ≤0)
+ * @param {number} [opts.killGraceMs] пауза між `SIGTERM` і ескалацією до `SIGKILL` (дефолт 5000)
+ * @param {string} [opts.cwd] робочий каталог дочірнього процесу
+ * @param {Record<string, string>} [opts.env] оточення дочірнього процесу
+ * @returns {Promise<SpawnAsyncResult>} нормалізований результат виконання
+ */
+export async function spawnAsync(cmd, args, opts = {}) {
+  const { signal, timeoutMs, killGraceMs = 5000, ...spawnOpts } = opts
+  if (signal?.aborted) throw new AbortError()
+
+  const child = spawn(cmd, args, spawnOpts)
+  child.stdout?.setEncoding('utf8')
+  child.stderr?.setEncoding('utf8')
+
+  let stdout = ''
+  let stderr = ''
+  child.stdout?.on('data', chunk => {
+    stdout += chunk
+  })
+  child.stderr?.on('data', chunk => {
+    stderr += chunk
+  })
+
+  let timedOut = false
+  let aborted = false
+  let settled = false
+  let killTimer = null
+  let timeoutTimer = null
+
+  /** SIGTERM негайно, ескалація до SIGKILL якщо процес не завершився за killGraceMs. */
+  const killWithEscalation = () => {
+    child.kill('SIGTERM')
+    killTimer = setTimeout(() => {
+      if (!settled) child.kill('SIGKILL')
+    }, killGraceMs)
+    killTimer.unref?.()
+  }
+  const onAbort = () => {
+    aborted = true
+    killWithEscalation()
+  }
+  if (signal) signal.addEventListener('abort', onAbort)
+  if (timeoutMs && timeoutMs > 0) {
+    timeoutTimer = setTimeout(() => {
+      timedOut = true
+      killWithEscalation()
+    }, timeoutMs)
+    timeoutTimer.unref?.()
+  }
+
+  /** @returns {Promise<{code: number|null, killSignal: string|null}>} результат події `close` */
+  const waitForClose = async () => {
+    const [code, killSignal] = await once(child, 'close')
+    return { code, killSignal }
+  }
+  /** @returns {Promise<never>} ніколи не резолвиться — кидає подію `error` */
+  const waitForError = async () => {
+    const [error] = await once(child, 'error')
+    throw error
+  }
+
+  try {
+    const { code, killSignal } = await Promise.race([waitForClose(), waitForError()])
+    return { stdout, stderr, exitCode: code, signal: killSignal, timedOut, aborted }
+  } finally {
+    settled = true
+    if (killTimer) clearTimeout(killTimer)
+    if (timeoutTimer) clearTimeout(timeoutTimer)
+    if (signal) signal.removeEventListener('abort', onAbort)
+  }
+}