@7n/rules 1.49.25 → 1.50.0

package/rules/k8s/manifests/main.mjs

@@ -6690,8 +6690,13 @@ export async function lint(ctx) {
   // (spec docs/specs/2026-07-02-text-check-per-file-split-design.md §6) ──
   const dirs = await findK8sRoots(root, ignorePaths)
   if (dirs.length > 0) {
-    const ks = await runKubescape(dirs, root, verbose)
-    if (ks !== 0 && ks !== 127) fail('kubescape знайшов ризики у маніфестах (k8s.mdc)', 'kubescape')
+    const ks = await runKubescape(dirs, root, verbose, { onProgress: ctx.reportProgressDetail })
+    if (ks.status !== 0 && ks.status !== 127) {
+      const message = ks.timedOut
+        ? `kubescape timeout: ${relative(root, ks.target)} (ліміт ${KUBESCAPE_SCAN_TIMEOUT_LABEL})`
+        : 'kubescape знайшов ризики у маніфестах (k8s.mdc)'
+      fail(message, 'kubescape')
+    }
   }
 
   // ── JS/rego cross-file перевірки (колишній check, read-only) ──
@@ -6798,6 +6803,10 @@ export async function findK8sRoots(root, ignorePaths = []) {
 const KUBESCAPE_EXCEPTIONS_FILE = '.kubescape-exceptions.json'
 const KUSTOMIZATION_FILE = 'kustomization.yaml'
 const KUBESCAPE_MISSING_HINT = 'kubescape не знайдено в PATH. Встанови з https://github.com/kubescape/kubescape#readme'
+/** Bounded wall-clock limit кожного зовнішнього scan; spawnAsync завершує child process. */
+export const KUBESCAPE_SCAN_TIMEOUT_MS = 5 * 60_000
+const KUBESCAPE_SCAN_TIMEOUT_LABEL = '5 хв'
+const KUBESCAPE_SCAN_TIMEOUT_ARG = '5m'
 const KUBERNETES_VERSION = '1.33.9'
 const DATREE_CRD_SCHEMA_LOCATION =
   'https://datreeio.github.io/CRDs-catalog/{{.Group}}/{{.ResourceKind}}_{{.ResourceAPIVersion}}.json'
@@ -7004,9 +7013,11 @@ async function runKustomizeBuild(kubectlPath, dir, verbose = false) {
  * @param {string|Buffer} manifest вміст маніфеста для сканування.
  * @param {string} root корінь репозиторію (для user-файла винятків).
  * @param {boolean} [verbose] показати повний нативний вивід kubescape (`stdio: 'inherit'`).
- * @returns {Promise<{ status: number, enoent: boolean }>} exit-код і прапорець відсутнього тула.
+ * @param {{ spawn?: typeof spawnAsync, useDefault?: boolean }} [opts] тестова інʼєкція spawn і cache-safe режим після першого target-а.
+ * @returns {Promise<{ status: number, enoent: boolean, timedOut: boolean }>} exit-код, відсутність тула і timeout.
  */
-async function runKubescapeManifest(kubescapePath, manifest, root, verbose = false) {
+export async function runKubescapeManifest(kubescapePath, manifest, root, verbose = false, opts = {}) {
+  const exec = opts.spawn ?? spawnAsync
   const dir = mkdtempSync(join(tmpdir(), 'nitra-cursor-k8s-'))
   const file = join(dir, 'manifest.yaml')
   const exceptionsArgs = buildKubescapeExceptionsArgs(root, autoJobCronJobProbeExceptions(String(manifest)))
@@ -7014,13 +7025,24 @@ async function runKubescapeManifest(kubescapePath, manifest, root, verbose = fal
   try {
     writeFileSync(file, manifest)
     try {
-      const r = await spawnAsync(kubescapePath, ['scan', file, '--severity-threshold', 'high', ...exceptionsArgs], {
-        stdio: verbose ? 'inherit' : 'pipe'
-      })
-      return { status: r.exitCode ?? 1, enoent: false }
+      const r = await exec(
+        kubescapePath,
+        [
+          'scan',
+          file,
+          '--severity-threshold',
+          'high',
+          '--scan-timeout',
+          KUBESCAPE_SCAN_TIMEOUT_ARG,
+          ...(opts.useDefault ? ['--use-default'] : []),
+          ...exceptionsArgs
+        ],
+        { stdio: verbose ? 'inherit' : 'pipe', timeoutMs: KUBESCAPE_SCAN_TIMEOUT_MS }
+      )
+      return { status: r.exitCode ?? 1, enoent: false, timedOut: r.timedOut === true }
     } catch (error) {
       const enoent = Boolean(error && error.code === 'ENOENT')
-      return { status: 1, enoent }
+      return { status: 1, enoent, timedOut: false }
     }
   } finally {
     cleanupKubescapeExceptionsArgs(exceptionsArgs, root)
@@ -7036,24 +7058,37 @@ async function runKubescapeManifest(kubescapePath, manifest, root, verbose = fal
  * @param {string} dir каталог для сканування.
  * @param {string} root корінь репозиторію (для user-файла винятків).
  * @param {boolean} [verbose] показати повний нативний вивід kubescape (`stdio: 'inherit'`) і хід сканування.
- * @returns {Promise<number>} exit-код (127 якщо тул відсутній).
+ * @param {{ spawn?: typeof spawnAsync, useDefault?: boolean }} [opts] тестова інʼєкція spawn і cache-safe режим після першого target-а.
+ * @returns {Promise<{ status: number, timedOut: boolean }>} exit-код (127 якщо тул відсутній) і timeout.
  */
-async function scanRawK8sDir(kubescapePath, dir, root, verbose = false) {
+async function scanRawK8sDir(kubescapePath, dir, root, verbose = false, opts = {}) {
+  const exec = opts.spawn ?? spawnAsync
   if (verbose) console.log(`run-k8s: kubescape scan ${dir} (без kustomization — сирий dir-скан)`)
   const yamlText = await readAllYamlTextUnderDir(dir)
   const exceptionsArgs = buildKubescapeExceptionsArgs(root, autoJobCronJobProbeExceptions(yamlText))
   if (verbose && exceptionsArgs.length > 0) console.log(`run-k8s: kubescape exceptions — ${exceptionsArgs[1]}`)
   try {
-    const r = await spawnAsync(kubescapePath, ['scan', dir, '--severity-threshold', 'high', ...exceptionsArgs], {
-      stdio: verbose ? 'inherit' : 'pipe'
-    })
-    return r.exitCode ?? 1
+    const r = await exec(
+      kubescapePath,
+      [
+        'scan',
+        dir,
+        '--severity-threshold',
+        'high',
+        '--scan-timeout',
+        KUBESCAPE_SCAN_TIMEOUT_ARG,
+        ...(opts.useDefault ? ['--use-default'] : []),
+        ...exceptionsArgs
+      ],
+      { stdio: verbose ? 'inherit' : 'pipe', timeoutMs: KUBESCAPE_SCAN_TIMEOUT_MS }
+    )
+    return { status: r.exitCode ?? 1, timedOut: r.timedOut === true }
   } catch (error) {
     if (error && error.code === 'ENOENT') {
       console.error(KUBESCAPE_MISSING_HINT)
-      return 127
+      return { status: 127, timedOut: false }
     }
-    return 1
+    return { status: 1, timedOut: false }
   } finally {
     cleanupKubescapeExceptionsArgs(exceptionsArgs, root)
   }
@@ -7066,21 +7101,22 @@ async function scanRawK8sDir(kubescapePath, dir, root, verbose = false) {
  * @param {string[]} kdirs каталоги з kustomization.
  * @param {string} root корінь репозиторію (для user-файла винятків).
  * @param {boolean} [verbose] показати повний нативний вивід kubectl/kubescape і хід сканування.
- * @returns {Promise<number>} 0 якщо всі чисті, інакше перший ненульовий exit-код (127 — тул відсутній).
+ * @param {{ spawn?: typeof spawnAsync, useDefault?: boolean }} [opts] тестова інʼєкція spawn і cache-safe режим після першого target-а.
+ * @returns {Promise<{ status: number, target: string|null, timedOut: boolean }>} результат одного або кількох target-ів.
  */
-async function scanKustomizeK8sDirs(kubectlPath, kubescapePath, kdirs, root, verbose = false) {
+async function scanKustomizeK8sDirs(kubectlPath, kubescapePath, kdirs, root, verbose = false, opts = {}) {
   for (const kdir of kdirs) {
     if (verbose) console.log(`run-k8s: kubectl kustomize ${kdir} | kubescape scan <tmp>`)
     const build = await runKustomizeBuild(kubectlPath, kdir, verbose)
-    if (build.status !== 0) return build.status
-    const ks = await runKubescapeManifest(kubescapePath, build.stdout, root, verbose)
+    if (build.status !== 0) return { status: build.status, target: kdir, timedOut: false }
+    const ks = await runKubescapeManifest(kubescapePath, build.stdout, root, verbose, opts)
     if (ks.enoent) {
       console.error(KUBESCAPE_MISSING_HINT)
-      return 127
+      return { status: 127, target: kdir, timedOut: false }
     }
-    if (ks.status !== 0) return ks.status
+    if (ks.status !== 0) return { status: ks.status, target: kdir, timedOut: ks.timedOut }
   }
-  return 0
+  return { status: 0, target: null, timedOut: false }
 }
 
 /**
@@ -7090,27 +7126,47 @@ async function scanKustomizeK8sDirs(kubectlPath, kubescapePath, kdirs, root, ver
  * @param {string[]} dirs абсолютні шляхи k8s-коренів.
  * @param {string} root корінь репозиторію (для user-файла винятків).
  * @param {boolean} [verbose] показати повний нативний вивід kubectl/kubescape (`stdio: 'inherit'`) і хід сканування.
- * @returns {Promise<number>} 0 якщо все чисто, інакше перший ненульовий exit-код (127 — тул відсутній).
+ * @param {{ kubescapePath?: string, kubectlPath?: string, spawn?: typeof spawnAsync, onProgress?: (progress: { label: string, done: number, total: number, current: string }) => void }} [opts] залежності й granular live progress.
+ * @returns {Promise<{ status: number, target: string|null, timedOut: boolean }>} результат усіх target-ів.
  */
-async function runKubescape(dirs, root, verbose = false) {
-  const kubescapePath = ensureTool('kubescape')
+export async function runKubescape(dirs, root, verbose = false, opts = {}) {
+  const kubescapePath = opts.kubescapePath ?? ensureTool('kubescape')
   let kubectlPath = null
+  /** @type {Array<{ kind: 'raw'|'kustomize', dir: string }>} */
+  const targets = []
   for (const d of dirs) {
     const kdirs = await findKustomizationDirs(d)
     if (kdirs.length === 0) {
-      const rawStatus = await scanRawK8sDir(kubescapePath, d, root, verbose)
-      if (rawStatus !== 0) return rawStatus
-      continue
+      targets.push({ kind: 'raw', dir: d })
+    } else {
+      for (const dir of kdirs) targets.push({ kind: 'kustomize', dir })
     }
-    if (kubectlPath === null) {
-      kubectlPath = resolveCmd('kubectl')
-      if (!kubectlPath) {
-        console.error('kubectl не знайдено в PATH. Встанови з https://kubernetes.io/docs/tasks/tools/#kubectl')
-        return 127
+  }
+
+  let done = 0
+  let cacheReady = false
+  for (const target of targets) {
+    opts.onProgress?.({ label: 'kubescape', done, total: targets.length, current: relative(root, target.dir) })
+    if (target.kind === 'raw') {
+      const result = await scanRawK8sDir(kubescapePath, target.dir, root, verbose, { ...opts, useDefault: cacheReady })
+      if (result.status !== 0) return { ...result, target: target.dir }
+    } else {
+      if (kubectlPath === null) {
+        kubectlPath = opts.kubectlPath ?? resolveCmd('kubectl')
+        if (!kubectlPath) {
+          console.error('kubectl не знайдено в PATH. Встанови з https://kubernetes.io/docs/tasks/tools/#kubectl')
+          return { status: 127, target: target.dir, timedOut: false }
+        }
       }
+      const result = await scanKustomizeK8sDirs(kubectlPath, kubescapePath, [target.dir], root, verbose, {
+        ...opts,
+        useDefault: cacheReady
+      })
+      if (result.status !== 0) return result
     }
-    const buildStatus = await scanKustomizeK8sDirs(kubectlPath, kubescapePath, kdirs, root, verbose)
-    if (buildStatus !== 0) return buildStatus
+    cacheReady = true
+    done += 1
+    opts.onProgress?.({ label: 'kubescape', done, total: targets.length, current: relative(root, target.dir) })
   }
-  return 0
+  return { status: 0, target: null, timedOut: false }
 }

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

@@ -3,71 +3,35 @@ type: JS Module
 title: resolve-plugins.mjs
 resource: npm/scripts/lib/resolve-plugins.mjs
 docgen:
-  crc: 52b1765f
-  model: omlx/gemma-4-e2b-it-4bit
-  tier: local-min
-  score: 40
-  issues: internal-name:hasLangSignal,internal-name:listScannableSubdirs,internal-name:readRepositoryUrl,internal-name:hasGithubWorkflows,internal-name:detectCiPlugins,surzhik,best-of-2:retry-error
+  crc: e7eaf408
+  model: openai-codex/gpt-5.5
+  tier: cloud-avg
+  score: 90
+  issues: surzhik,judge-refine:kept-original,judge:inaccurate:0.99
+  judgeModel: openai-codex/gpt-5.4-mini
 ---
 
 ## Огляд
 
-Огляд: Цей файл забезпечує пошук сигналів-маркерів у файловій системі для визначення активності плагінів. Він використовує BFS-обхід для пошуку цих сигналів, визначає доступні `capabilities`, розв'язує список плагінів з конфігурації, гарантує встановлення необхідних пакетів, обробляє маніфести плагінів та надає інструменти для роботи з їхніми обробниками (`handlers`).
+Файл визначає, які плагіни `@7n/rules` активні для проєкту, щоб core міг підключити правильні каталоги правил, capabilities, документаційні розширення та handlers. Джерело правди — поле `plugins: string[]` у `.n-rules.json`: явний `[]` вимикає плагіни й автодетект, а відсутнє поле запускає повний `detectPluginsFromRepo`.
 
-## Поведінка
-
-Перевіряє наявність файлу-сигналу у корені або підтеках до `maxDepth` рівнів. Використовує BFS-обхід, який пропускає приховані директорії, `node_modules`, та `target`, для забезпечення ефективного виклику на hot-path. Повертає `true` при знаходженні сигналу. Викликає `listScannableSubdirs`.
-
-### listScannableSubdirs
-Отримує видимі підтеки для неглибокого скану, ігноруючи приховані та службові директорії. Повертає масив абсолютних шляхів підтеків (порожній, якщо директорія нечитабельна).
-
-### readRepositoryUrl
-Отримує `repository.url` з кореневого `package.json` (як рядок або об'єкт). Повертає `null`, якщо URL відсутній або файл нечитабельний.
-
-### hasGithubWorkflows
-Перевіряє наявність файлів у директорії `.github/workflows/` будь-якого YAML/YML файлу. Повертає `true` при наявності.
-
-### detectCiPlugins
-Автоматично визначає CI-плагіни за станом репозиторію. Пріоритет надається файловим сигналам. Якщо файлових сигналів немає, використовується `repository.url` з кореневого `package.json`. Якщо обидва сигнали присутні, обидва плагіни повертаються. Якщо немає жодного сигналу, повертається порожній масив. Викликає `hasGithubWorkflows` та `readRepositoryUrl`.
+Якщо `plugins` непорожній і містить лише пакети за конвенцією `@7n/rules-<category>-<name>`, автодетект домішує тільки відсутні категорії. Будь-який сторонній пакет у списку вимикає backfill повністю, щоб змішана або користувацька конфігурація залишалась ручною й передбачуваною.
 
-### detectPluginsFromRepo
-Автоматично визначає плагіни за станом репозиторію. Використовує файлові сигнали як пріоритет, з fallback на `repository.url` лише для CI-плагінів, коли файлових сигналів немає. Для Rust використовується перевірка до трьох рівнів підтек. Викликає `detectCiPlugins` та `hasLangSignal`.
+Автодетект спирається на файлові сигнали `.github/workflows/*.yml` і `azure-pipelines.yml`, а за їх відсутності — на `repository.url` з ознаками `github.com` або `dev.azure.com`. Резолв працює fail-safe: недоступні, не встановлені або несумісні плагіни не зривають lint/sync, а пропускаються; для несумісного `requiresPluginApi > PLUGIN_API_VERSION` видається warning, крім режиму `quiet:true`, де пропуск тихий. Результати кешуються в межах прогону.
 
-### pluginCategory
-Визначає категорію плагіна на основі naming convention `@7n/rules-<category>-<name>`. Повертає `null` для пакетів, що не відповідають цій конвенції (сторонні/кастомні плагіни) — такий пакет ніколи не з'являється сам через автодетект, а якщо присутній у явному `config.plugins`, вимикає backfill категорій для всього списку.
-
-### resolvePluginList
-Обчислює список плагінів проєкту. Використовує явне поле `config.plugins` з `.n-rules.json` або автоматичний автодетект. Явний пустий масив означає "плагіни вимкнено". Якщо `config.plugins` містить сторонній пакет, який не є `@7n/rules-*`, то backfill для заповнення списку вимикається повністю.
-
-### computePluginList
-Обчислює список плагінів без кешу. Використовує сире значення `config.plugins` з `.n-rules.json`. Повертає список плагінів. Викликає `detectPluginsFromRepo` та `pluginCategory`.
-
-### ensurePluginInstalled
-Гарантує наявність пакета: якщо він відсутній у `node_modules`, виконує `bun add -d <pkg>` для додання його як `devDependency`. Фейл повертає `false` з попередженням.
-
-### readPluginManifest
-Отримує нормалізований маніфест плагіна з його `package.json` з блоку `"n-rules"`.
-
-### resolvePlugins
-Виконує повне визначення доступних плагінів проєкту з використанням кешу. Дозволяє встановити вже встановлені пакети через `allowInstall: false` (для hot-path хука), ігнорує `bun add`, ігнорує `quiet` для уникнення попереджень при виклику на кожному файлі. Повертає масив доступних плагінів.
+## Поведінка
 
-### resolveRulesDirs
-Отримує шляхи до каталогів для всіх поверхонь ядра. Ядро має пріоритет. Надає масив об'єктів, що містять ім'я плагіна, шлях до його директорії та шлях до його кореня пакета.
+`resolvePluginList` бере список із `.n-rules.json`: відсутнє поле запускає повний автодетект через `detectPluginsFromRepo`, явний порожній список вимикає плагіни, а непорожній список може доповнюватися лише відсутніми категоріями. `pluginCategory` визначає ці категорії; якщо у списку є сторонній пакет, backfill не застосовується.
 
-### getActiveCapabilities
-Отримує набір capability-рядків з усіх доступних плагінів, що використовуються для визначення `requires.capability` у `concern.json`.
+`detectPluginsFromRepo` зіставляє файлові сигнали з `KNOWN_CI_PLUGINS` і `KNOWN_LANG_PLUGINS`. Для CI файлові сигнали мають пріоритет, а fallback за URL з кореневого `package.json` використовується лише коли CI-конфігів немає. Для мов працюють тільки файлові сигнали; під час неглибокого скану службові й приховані каталоги на кшталт `.github`, `.git` і `node_modules` не обходяться.
 
-### getDocFilesExtensions
-Агрегує розширення файлів, що використовуються для генерації мапи від розширення до типу-мітка. Повертає мапу `extension -> type-мітка`.
+`resolvePlugins` перетворює обрані імена на доступні плагіни: за потреби делегує встановлення в `ensurePluginInstalled`, читає маніфест, відкидає несумісні плагіни й не зриває виконання через недоступний пакет. `KNOWN_PLUGIN_RANGES` обмежує версії first-party плагінів під час автоматичного встановлення, щоб core і плагіни лишалися сумісними.
 
-### getUnavailableDeclaredPlugins
-Повертає список плагінів, які задекларовані у `config.plugins`, але відсутні у `node_modules`. Нічого не встановлює і нічого не друкує — чистий предикат для explicit CLI-діагностики.
+Результати резолву кешуються в межах процесу, щоб повторні виклики з тих самих даних не дублювали сканування, встановлення та попередження. `clearPluginResolveCache` скидає цей спільний стан для ізольованих перевірок.
 
-### getHandlers
-Отримує шляхи до модулів-обробників для певного extension-point правила ядра.
+`resolveRulesDirs` використовує `resolvePlugins`, щоб зібрати джерела правил: core іде першим, далі активні плагіни у визначеному порядку. `getActiveCapabilities` агрегує capabilities з маніфестів; ці значення використовуються для гейтів у `concern.json`.
 
-### clearPluginResolveCache
-Скидає кеш, призначений для тестів.
+`getDocFilesExtensions` і `getHandlers` читають внесок активних плагінів для документаційних розширень та extension-points. `getUnavailableDeclaredPlugins` окремо перевіряє саме явно задекларовані, але недоступні пакети, щоб CLI міг показати діагностику без автоматичного встановлення.
 
 ## Публічний API
 
@@ -98,8 +62,17 @@ per-категорійний backfill для всього списку (див.
 (через `resolveRulesDirs` тощо) і прямий виклик у sync-CLI інакше дублювали б і файловий
 скан, і warning про backfill.
   ігнорується при cache hit — warning друкується щонайбільше раз на `(root, declared)` за процес
+- KNOWN_PLUGIN_RANGES — Сумісний semver-range для first-party плагінів: обмежує автоматичну інсталяцію (`ensurePluginInstalled`)
+поточною core-сумісною лінією, щоб майбутній несумісний major/minor плагіна не встановився
+мовчки поверх старого core (Фаза 0, spec 2026-07-27-universal-plugin-slots-lang-php-extraction.md
+§10). Для `0.x`-пакетів — caret на поточний minor (`^0.22`, а не голий `^0`, який під caret-
+семантикою розгортається у весь діапазон `0.x`); для `>=1` — caret на поточний major (`^1`).
+Невідомий (сторонній, не з цієї таблиці) пакет інсталюється без обмеження версії — як і раніше.
 - ensurePluginInstalled — Гарантує, що плагін встановлений: якщо `node_modules/<pkg>` нема — `bun add -d <pkg>`
-(дописує devDependency і ставить). Фейл — warning + false, без винятку.
+(дописує devDependency і ставить). Для first-party пакетів з `KNOWN_PLUGIN_RANGES` версія
+обмежується сумісним range (`<pkg>@^<major>` або `@^<major>.<minor>` для `0.x`); сторонні
+пакети встановлюються без обмеження, bun сам резолвить latest. Фейл — warning + false, без
+винятку.
 - resolvePlugins — Повний резолв плагінів проєкту (з кешем на процес).
   лише вже встановлені пакети, без `bun add`; `quiet` — без warning-ів (hook на кожен файл)
 - resolveRulesDirs — Rules-каталоги для всіх поверхонь ядра: ядро першим (його правила/концерни виграють

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

@@ -66,6 +66,15 @@ const NON_TTY_WAIT_LOG_INTERVAL_MS = 10_000
 /** Знімок прогресу вважається живим, якщо оновлювався не давніше за це. */
 const PROGRESS_FRESH_MS = 60_000
 
+/** Версія контракту published snapshot-а; observer-и ігнорують неповні старі записи. */
+const PROGRESS_SNAPSHOT_VERSION = 2
+
+/** Частота heartbeat owner-а: довгий один target лишається видимим для процесу в черзі. */
+const PUBLISH_HEARTBEAT_INTERVAL_MS = 5_000
+
+/** Мінімум завершених targets, коли швидкість вже достатня для обережного ETA. */
+const ETA_MIN_COMPLETED_TARGETS = 3
+
 /**
  * Fingerprint для TTL-дедуплікації: стан робочого дерева + варіант виклику lint.
  * null (→ дедуплікація вимкнена, черга працює) коли:
@@ -90,26 +99,68 @@ export function lintLockFingerprint(variant, getTreeFp = worktreeFingerprint) {
  * Publisher прогресу активного прогону: приймає знімки від
  * `createProgressReporter({ onUpdate })` і (throttled) пише їх у стан-файл,
  * звідки процеси в черзі читають прогрес-бар активного прогону.
- * @param {{file?: string, minIntervalMs?: number}} [opts] override-и для тестів
- * @returns {{ onUpdate: (snap: { done: number, total: number, found: number, fixed: number, current: string }) => void, stop: () => void }} publisher
+ * @param {{file?: string, minIntervalMs?: number, heartbeatIntervalMs?: number, now?: () => number}} [opts] override-и для тестів
+ * @returns {{ onUpdate: (snap: { done: number, total: number, found: number, fixed: number, current: string, detail?: { label: string, done: number, total: number, current: string } | null }) => void, stop: () => void }} publisher
  */
 export function createProgressPublisher(opts = {}) {
   const file = opts.file ?? PROGRESS_FILE
   const minIntervalMs = opts.minIntervalMs ?? PUBLISH_MIN_INTERVAL_MS
+  const heartbeatIntervalMs = opts.heartbeatIntervalMs ?? PUBLISH_HEARTBEAT_INTERVAL_MS
+  const now = opts.now ?? Date.now
   let lastWriteAt = 0
+  let lastSnap = null
+  let phaseStartedAt = 0
+
+  /** Записує атомарно достатній для observer-а snapshot; помилки лишаються best-effort. */
+  function publish(snap, heartbeat = false) {
+    const at = now()
+    const detail = snap.detail ?? null
+    if (!heartbeat && (!lastSnap || lastSnap.current !== snap.current || lastSnap.detail?.label !== detail?.label))
+      phaseStartedAt = at
+    const completed = detail?.done ?? 0
+    const remaining = Math.max(0, (detail?.total ?? 0) - completed)
+    const elapsed = phaseStartedAt > 0 ? at - phaseStartedAt : 0
+    const etaMs =
+      !heartbeat && detail && completed >= ETA_MIN_COMPLETED_TARGETS && remaining > 0 && elapsed > 0
+        ? Math.round((elapsed / completed) * remaining)
+        : (lastSnap?.etaMs ?? null)
+    const record = {
+      version: PROGRESS_SNAPSHOT_VERSION,
+      pid: process.pid,
+      cwd: processCwd(),
+      updatedAt: heartbeat ? (lastSnap?.updatedAt ?? at) : at,
+      heartbeatAt: at,
+      phase: snap.current,
+      step: detail?.label ?? null,
+      done: snap.done,
+      total: snap.total,
+      found: snap.found,
+      fixed: snap.fixed,
+      current: snap.current,
+      detail,
+      etaMs
+    }
+    lastSnap = record
+    try {
+      mkdirSync(dirname(file), { recursive: true })
+      writeFileSync(file, JSON.stringify(record))
+    } catch {
+      // best-effort: без стан-файлу процеси в черзі просто не побачать бар
+    }
+  }
+  const heartbeat = setInterval(() => {
+    if (lastSnap) publish(lastSnap, true)
+  }, heartbeatIntervalMs)
+  heartbeat.unref?.()
   return {
     onUpdate: snap => {
-      const now = Date.now()
-      if (now - lastWriteAt < minIntervalMs) return
-      lastWriteAt = now
-      try {
-        mkdirSync(dirname(file), { recursive: true })
-        writeFileSync(file, JSON.stringify({ pid: process.pid, updatedAt: now, cwd: processCwd(), ...snap }))
-      } catch {
-        // best-effort: без стан-файлу процеси в черзі просто не побачать бар
-      }
+      const at = now()
+      if (at - lastWriteAt < minIntervalMs) return
+      lastWriteAt = at
+      publish(snap)
     },
     stop: () => {
+      clearInterval(heartbeat)
       try {
         rmSync(file, { force: true })
       } catch {
@@ -155,13 +206,14 @@ function listQueue(queueDir) {
  * застарілий або належить не поточному власнику лока.
  * @param {number} ownerPid PID власника лока
  * @param {string} progressFile шлях стан-файлу прогресу
- * @returns {{ done: number, total: number, found: number, fixed: number, current: string } | null} знімок
+ * @returns {{ done: number, total: number, found: number, fixed: number, current: string, phase: string, step: string|null, detail: { label: string, done: number, total: number, current: string }|null, etaMs: number|null, updatedAt: number, heartbeatAt: number } | null} знімок
  */
-function readOwnerProgress(ownerPid, progressFile) {
+export function readOwnerProgress(ownerPid, progressFile) {
   try {
     const snap = JSON.parse(readFileSync(progressFile, 'utf8'))
     if (snap?.pid !== ownerPid) return null
-    if (Date.now() - snap.updatedAt > PROGRESS_FRESH_MS) return null
+    if (snap?.version !== PROGRESS_SNAPSHOT_VERSION || typeof snap.heartbeatAt !== 'number') return null
+    if (Date.now() - snap.heartbeatAt > PROGRESS_FRESH_MS) return null
     return snap
   } catch {
     return null
@@ -180,7 +232,11 @@ export function renderWaitLine(owner, queue, snap) {
   const myIdx = queue.findIndex(e => e.pid === process.pid)
   const pos = (myIdx === -1 ? queue.length : myIdx) + 1
   const ownerDir = owner.cwd ? ` (${basename(owner.cwd)})` : ''
-  const bar = snap ? ` · ${renderProgressLine(snap)}` : ''
+  const eta =
+    snap?.etaMs !== null && snap?.etaMs !== undefined && Date.now() - snap.updatedAt <= PROGRESS_FRESH_MS
+      ? ` · ETA ≈ ${formatEta(snap.etaMs)}`
+      : ''
+  const bar = snap ? ` · ${renderProgressLine(snap)}${eta}` : ''
   const others = queue
     .filter(e => e.pid !== process.pid)
     .map(e => `pid ${e.pid} (${basename(e.cwd)})`)
@@ -189,6 +245,13 @@ export function renderWaitLine(owner, queue, snap) {
   return `⏳ lint --full у черзі #${pos}/${Math.max(queue.length, pos)} · працює pid ${owner.pid}${ownerDir}${bar}${tail}`
 }
 
+/** Форматує короткий ETA; caller передає лише вже перевірену обережну оцінку. */
+function formatEta(ms) {
+  const seconds = Math.max(1, Math.round(ms / 1000))
+  if (seconds < 60) return `${seconds} с`
+  return `${Math.ceil(seconds / 60)} хв`
+}
+
 /**
  * UI очікування для хуків withLock: реєструє процес у черзі, на кожен tick
  * рендерить рядок стану (TTY — перемальовування одного рядка на stderr;
@@ -213,13 +276,15 @@ function createWaitUi(opts = {}) {
       } catch {
         // best-effort: без реєстрації процес просто не видно у списку черги
       }
+      // non-TTY мусить сказати про очікування одразу, а не через перший інтервал poll-а.
+      lastAppendAt = 0
     },
     onWaitTick: owner => {
       const line = renderWaitLine(owner, listQueue(queueDir), readOwnerProgress(owner.pid, progressFile))
       if (isTTY) {
         // \r + ANSI clear-line: один рядок, що перемальовується на кожен tick
         log(`\r\u{1B}[2K${line}`)
-      } else if (Date.now() - lastAppendAt >= NON_TTY_WAIT_LOG_INTERVAL_MS) {
+      } else if (lastAppendAt === 0 || Date.now() - lastAppendAt >= NON_TTY_WAIT_LOG_INTERVAL_MS) {
         lastAppendAt = Date.now()
         log(`${line}\n`)
       }

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

@@ -22,7 +22,7 @@ const BAR_WIDTH = 20
  * Рендерить один рядок прогресу — спільний формат для TTY-бара цього reporter-а
  * та для прогресу чужого прогону, який показує процес у черзі
  * (`lint-lock.mjs` читає знімок зі стан-файлу і показує його тим самим рядком).
- * @param {{ done: number, total: number, found: number, fixed: number, current: string, unitLabel?: string, withFixed?: boolean }} snap знімок прогресу
+ * @param {{ done: number, total: number, found: number, fixed: number, current: string, unitLabel?: string, withFixed?: boolean, detail?: { label: string, done: number, total: number, current: string } | null }} snap знімок прогресу
  * @returns {string} готовий рядок бара
  */
 export function renderProgressLine(snap) {
@@ -31,7 +31,10 @@ export function renderProgressLine(snap) {
   const filled = Math.round(progress * BAR_WIDTH)
   const bar = '█'.repeat(filled) + '░'.repeat(BAR_WIDTH - filled)
   const ticker = (snap.withFixed ?? true) ? ` · знайдено ${snap.found} · виправлено ${snap.fixed}` : ''
-  return `[${bar}] ${snap.done}/${snap.total} ${unitLabel}${ticker} · ${snap.current}`
+  const sub = snap.detail
+    ? ` · ${snap.detail.label} ${snap.detail.done}/${snap.detail.total} · ${snap.detail.current}`
+    : ''
+  return `[${bar}] ${snap.done}/${snap.total} ${unitLabel}${ticker} · ${snap.current}${sub}`
 }
 
 /**
@@ -61,6 +64,7 @@ function formatBar(_options, params, payload) {
  * @property {(label: string, tier?: string) => void} concernStart оновити суфікс поточної одиниці
  * @property {(key: string, count: number) => void} detectSnapshot знімок detect/re-detect (кількість порушень)
  * @property {(key: string) => void} concernDone одиницю оброблено (закриту чи ні) — бар +1
+ * @property {(detail: { label: string, done: number, total: number, current: string } | null) => void} detail опублікувати деталізацію поточного concern-а
  * @property {() => { done: number, total: number, found: number, fixed: number }} summary поточні лічильники
  * @property {() => void} stop фінальний render і звільнення TTY-рядка
  */
@@ -89,6 +93,8 @@ export function createProgressReporter(opts) {
   const counters = new Map()
   let done = 0
   let current = '…'
+  /** @type {{ label: string, done: number, total: number, current: string } | null} */
+  let detail = null
 
   /**
    * Пер-ключ стан лічильників (лениве створення).
@@ -139,7 +145,7 @@ export function createProgressReporter(opts) {
   /** Перемальовує бар актуальним payload-ом (TTY) і публікує знімок назовні. */
   function redraw() {
     const { found, fixed } = tally()
-    opts.onUpdate?.({ done, total, found, fixed, current })
+    opts.onUpdate?.({ done, total, found, fixed, current, detail })
     if (!bar) return
     bar.update(done, { unitLabel, withFixed, found, fixed, current })
   }
@@ -153,6 +159,12 @@ export function createProgressReporter(opts) {
 
     concernStart: (label, tier) => {
       current = tier ? `${label} (${tier})` : label
+      detail = null
+      redraw()
+    },
+
+    detail: next => {
+      detail = next
       redraw()
     },
 

package/scripts/lib/lint-surface/run-detectors.mjs

@@ -527,7 +527,15 @@ async function buildPlan({
  */
 async function runPlanItem({ entry, files }, { cwd, verbose, progress, log, signal }) {
   /** @type {LintContext} */
-  const ctx = { cwd, ruleId: entry.ruleId, concernId: entry.concern.name, files, verbose, signal }
+  const ctx = {
+    cwd,
+    ruleId: entry.ruleId,
+    concernId: entry.concern.name,
+    files,
+    verbose,
+    signal,
+    reportProgressDetail: progress?.detail
+  }
   const key = `${entry.ruleId}/${entry.concern.name}`
   progress?.concernStart(key)
   if (verbose) {

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

@@ -24,6 +24,8 @@
  * @property {AbortSignal} [signal] сигнал скасування — лише у parallel lane `detectAll()`
  *   (`N_RULES_LINT_CONCURRENCY>1`, ADR 260716-1354); async-детектори (`spawnAsync`-based)
  *   прокидають його далі, щоб перерватись при infrastructure-помилці іншого concern-а
+ * @property {(detail: { label: string, done: number, total: number, current: string } | null) => void} [reportProgressDetail]
+ *   optional read-only live detail поточного concern-а для full-lint observer-а
  */
 
 /**