@7n/rules 1.13.1 → 1.14.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## [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.0",
   "description": "CLI еталонних правил і skills (префікс n-): синк у репозиторій, дельта-lint, конформність",
   "keywords": [
     "cli",

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/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 }
 }