@7n/rules 1.49.26 → 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/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-а
  */
 
 /**

package/skills/doc-files/SKILL.md

@@ -13,9 +13,10 @@ version: '1.0'
 у теці `docs/` **поряд із самим файлом** (`<dir>/docs/<stem>.md`). Це **обовʼязковий крок кожної
 задачі** — як `lint`: після зміни коду його дока має бути перегенерована.
 
-Застарілість визначається **детерміновано за CRC**: кожна дока несе у frontmatter контрольну
-суму байтів джерела на момент генерації. Дока **застаріла**, якщо її немає або
-`crc(поточне джерело) ≠ crc у frontmatter`.
+Застарілість визначається **детерміновано за CRC evidence**: кожна дока несе у frontmatter
+контрольну суму source + повʼязаних test/spec-файлів на момент генерації. Без повʼязаних
+тестів це звичайний CRC source. Дока **застаріла**, якщо її немає або поточний evidence CRC
+не збігається з `crc` у frontmatter.
 
 ```markdown
 ---
@@ -60,6 +61,18 @@ npx @7n/rules lint doc-files
 (`stale`) → генерує локальною моделлю → пише доку зі **свіжим CRC** (і degraded-маркером,
 якщо не дотягнула) → друкує прогрес і підсумок.
 
+Повʼязані тести визначаються за relative reference, який резолвиться у source (`import`,
+`require`, dynamic import, `vi.mock` тощо), плюс naming/layout evidence (`foo.test` → `foo`
+або `module/tests/*` → module `main`/`index`). Shared test helpers, які тест лише імпортує,
+не стають evidence. JS детерміновано рендерить один компактний рядок на test-файл: до двох
+груп, пʼять дослівних прикладів і точний лічильник решти; test-код і сценарії не потрапляють до
+моделі. Зміна такого тесту робить source-доку stale.
+
+Авторські коментарі теж є першоджерелом: для JSDoc, rustdoc і Python docstring-ів JS дослівно
+збирає «Огляд» і «Публічний API». Детальний наратив дає `comment-only` (0 LLM); короткий
+pointer або складний flow — `comment+behavior`, де LLM дописує тільки «Поведінку», а judge
+перевіряє лише її. За неповних коментарів лишається звичайний `fallback`.
+
 ### Крок 2: Підтвердження
 
 Дочекайся підсумку `✓ OK: <N>  ⚠ degraded: <D>  ✗ Err: <E>`. Якщо є помилки — перелічи
@@ -80,7 +93,9 @@ preflight). Degraded — не помилка: дока існує, CRC свіж
 ## Нотатки
 
 - Не комітити автоматично — користувач вирішує, коли комітити згенеровану доку.
-- Scanner ігнорує `node_modules`, `dist`, `.git`, `__pycache__`, `coverage`, `.cursor`, `.claude`,
-  усі теки `docs/`, а також `*.test.*` / `*.spec.*` / `*.d.ts`. Кореневий repo `docs/` —
-  system-wide only: file-level docs туди не пишуться. Список glob-ів — `docgen-ignore.mjs`.
+- Scanner не створює окремих док для `*.test.*` / `*.spec.*`, але використовує повʼязані
+  тести як evidence для source-доки. Він ігнорує `node_modules`, `dist`, `.git`,
+  `__pycache__`, `coverage`, `.cursor`, `.claude`, усі теки `docs/` і `*.d.ts`.
+  Кореневий repo `docs/` — system-wide only: file-level docs туди не пишуться. Список
+  glob-ів — `docgen-ignore.mjs`.
 - Агрегуюча документація (module-summary, доменні доки) — окремий скіл `doc-aggregate`, за запитом.