@nitra/cursor 12.11.0 → 12.11.2

package/rules/test/coverage/coverage.mjs

@@ -1,317 +0,0 @@
-/**
- * Канонічна команда `n-cursor coverage`: збирає метрики покриття + мутаційного
- * тестування з усіх провайдерів, чиє правило активне в `.n-cursor.json#rules`,
- * агрегує та записує COVERAGE.md у корінь проєкту.
- *
- * Discovery провайдерів — за `.n-cursor.json#rules`: для кожного `ruleId` зі
- * списку шукаємо `npm/rules/<ruleId>/coverage/coverage.mjs` і динамічно
- * імпортуємо. Якщо файлу немає — провайдер для цього правила відсутній (skip
- * silently, не помилка).
- *
- * Лок — прямий виклик `withLock('coverage', steps)`. Один CLI-консумер, один
- * callsite — спільна точка входу не виноситься (YAGNI, див. C4 у
- * specs/2026-05-24-coverage-rule-design.md).
- */
-import { existsSync } from 'node:fs'
-import { readFile, writeFile } from 'node:fs/promises'
-import { dirname, join } from 'node:path'
-import { fileURLToPath, pathToFileURL } from 'node:url'
-
-import { applyVerdicts } from '../../../scripts/coverage-classify/apply.mjs'
-import { classify } from '../../../scripts/coverage-classify/index.mjs'
-import { collectChangedFilesSince, resolveChangedBase } from '../../../scripts/lib/changed-files.mjs'
-import { readNCursorConfigLite } from '../../../scripts/lib/read-n-cursor-config-lite.mjs'
-import { withLock } from '../../../scripts/utils/with-lock.mjs'
-
-/** Корінь `npm/rules/` — `<rules>/test/coverage` → `<rules>` */
-const RULES_DIR = dirname(dirname(dirname(fileURLToPath(import.meta.url))))
-
-/**
- * Сума двох coverage-totals.
- * @param {{lines:{covered:number,total:number}, functions:{covered:number,total:number}}} a перший subtotal
- * @param {{lines:{covered:number,total:number}, functions:{covered:number,total:number}}} b другий subtotal
- * @returns {{lines:{covered:number,total:number}, functions:{covered:number,total:number}}} сумарні lines/functions
- */
-export function addCoverage(a, b) {
-  return {
-    lines: { covered: a.lines.covered + b.lines.covered, total: a.lines.total + b.lines.total },
-    functions: {
-      covered: a.functions.covered + b.functions.covered,
-      total: a.functions.total + b.functions.total
-    }
-  }
-}
-
-/**
- * Сума двох mutation-counts.
- * @param {{caught:number,total:number}} a перший subtotal
- * @param {{caught:number,total:number}} b другий subtotal
- * @returns {{caught:number,total:number}} сумарні caught/total
- */
-export function addMutation(a, b) {
-  return { caught: a.caught + b.caught, total: a.total + b.total }
-}
-
-/**
- * Форматує covered/total як `XX.XX% (covered/total)`.
- * @param {{covered:number,total:number}} metric метрика lines або functions
- * @returns {string} відформатований рядок для таблиці COVERAGE.md
- */
-export function formatCoverage({ covered, total }) {
-  const percent = total === 0 ? '—' : `${((covered / total) * 100).toFixed(2)}%`
-  return `${percent} (${covered}/${total})`
-}
-
-/**
- * Форматує мутаційний score як `XX.XX%`.
- * @param {{caught:number,total:number}} metric агрегований mutation score
- * @returns {string} відформатований score або прочерк
- */
-export function formatScore({ caught, total }) {
-  return total === 0 ? '—' : `${((caught / total) * 100).toFixed(2)}%`
-}
-
-/**
- * Рендерить таблицю покриття + мутаційного тестування як Markdown.
- * Якщо будь-який рядок містить непустий `survived`, додає секцію
- * `## Вцілілі мутанти` з JSON-блоком для `/n-coverage-fix`.
- * Якщо `allowedGaps` непустий, додає секцію `## Allowed gaps` з таблицею
- * verdict/confidence/reason для кожного LLM-класифікованого мутанта.
- * Без timestamp, щоб git diff рухався лише при зміні метрик.
- * @param {Array<{area:string, coverage:{lines:{covered:number,total:number},functions:{covered:number,total:number}}, mutation:{caught:number,total:number}, survived?: Array<{file:string,line:number,col:number,mutantType:string,original:string,replacement:string}>}>} rows рядки провайдерів
- * @param {Array<{file:string, mutant:{line:number,col:number,mutantType:string,original:string,replacement:string}, verdict:{verdict:string,confidence:number,reason:string}}>} [allowedGaps] мутанти виключені класифікатором
- * @returns {string} Markdown з заголовком `# Coverage`
- */
-export function renderMarkdown(rows, allowedGaps = []) {
-  const lines = [
-    '# Coverage',
-    '',
-    '| Область | Рядки | Функції | Вбито мутацій | Score |',
-    '| --- | --- | --- | --- | --- |'
-  ]
-  for (const row of rows) {
-    lines.push(
-      `| ${row.area} | ${formatCoverage(row.coverage.lines)} | ${formatCoverage(row.coverage.functions)} | ` +
-        `${row.mutation.caught}/${row.mutation.total} | ${formatScore(row.mutation)} |`
-    )
-  }
-
-  const allSurvived = rows.flatMap(r => r.survived ?? [])
-  if (allSurvived.length > 0) {
-    lines.push('', '## Вцілілі мутанти', '', '```json', JSON.stringify(allSurvived, null, 2), '```')
-    // Зрозуміла для людини таблиця
-    for (const group of allSurvived) {
-      lines.push('', `### ${group.file}`, '', '| Рядок | Оригінал | Заміна | Тип |', '| --- | --- | --- | --- |')
-      for (const m of group.mutants) {
-        lines.push(`| ${m.line} | \`${m.original}\` | \`${m.replacement}\` | ${m.mutantType} |`)
-      }
-      if (group.exampleTest) {
-        lines.push(
-          '',
-          `**Приклад тесту** (\`${group.exampleTest.testFile}\`):`,
-          '',
-          '```js',
-          group.exampleTest.code ?? '',
-          '```'
-        )
-      }
-      if (group.recommendationText) {
-        lines.push('', '**Що треба протестувати:**', '', group.recommendationText)
-      }
-    }
-  }
-
-  if (allowedGaps.length > 0) {
-    // Group allowed gaps by file
-    const gapsByFile = new Map()
-    for (const gap of allowedGaps) {
-      if (!gapsByFile.has(gap.file)) gapsByFile.set(gap.file, [])
-      gapsByFile.get(gap.file).push(gap)
-    }
-
-    lines.push(
-      '',
-      '## Allowed gaps',
-      '',
-      `> LLM-класифікатор виключив ${allowedGaps.length} survived мутант(ів) зі знаменника mutation score.`,
-      '> Категорії: equivalent (поведінково еквівалентний), defensive (impossible state), glue/wrapper (integration test покриває).'
-    )
-
-    for (const [file, gaps] of gapsByFile) {
-      lines.push(
-        '',
-        `### ${file}`,
-        '',
-        '| Line | Mutant | Verdict | Confidence | Reason |',
-        '| --- | --- | --- | --- | --- |'
-      )
-      for (const { mutant, verdict } of gaps) {
-        const sanitizedReason = verdict.reason.replaceAll('|', String.raw`\|`).replaceAll('\n', ' ')
-        lines.push(
-          `| ${mutant.line} | \`${mutant.original}\` → \`${mutant.replacement}\` | ${verdict.verdict} | ${verdict.confidence.toFixed(2)} | ${sanitizedReason} |`
-        )
-      }
-    }
-  }
-
-  return `${lines.join('\n')}\n`
-}
-
-/**
- * Завантажує provider-модуль з `<rulesDir>/<ruleId>/coverage/coverage.mjs`.
- * Повертає null коли:
- *   - файлу немає (rule без coverage-провайдера),
- *   - файл існує, але не експортує `detect` + `collect` як функції (наприклад,
- *     `rules/test/coverage/coverage.mjs` — сам оркестратор, не провайдер).
- * @param {string} rulesDir корінь `npm/rules/`
- * @param {string} ruleId id правила з `.n-cursor.json#rules`
- * @returns {Promise<{detect:(cwd:string)=>Promise<boolean>, collect:(cwd:string)=>Promise<Array<object>>}|null>} provider-модуль або null
- */
-async function loadProvider(rulesDir, ruleId) {
-  const providerPath = join(rulesDir, ruleId, 'coverage', 'coverage.mjs')
-  if (!existsSync(providerPath)) return null
-  const mod = await import(pathToFileURL(providerPath).href)
-  if (typeof mod.detect !== 'function' || typeof mod.collect !== 'function') return null
-  return mod
-}
-
-/**
- * Будує підсумковий рядок «Разом» через сумування всіх coverage/mutation.
- * @param {Array<{area:string, coverage:object, mutation:object}>} rows рядки провайдерів без totals
- * @returns {{area:string, coverage:object, mutation:{caught:number,total:number}}} агрегований рядок «Разом»
- */
-function buildTotalsRow(rows) {
-  let totalCoverage = { lines: { covered: 0, total: 0 }, functions: { covered: 0, total: 0 } }
-  let totalMutation = { caught: 0, total: 0 }
-  for (const row of rows) {
-    totalCoverage = addCoverage(totalCoverage, row.coverage)
-    totalMutation = addMutation(totalMutation, row.mutation)
-  }
-  return { area: '**Разом**', coverage: totalCoverage, mutation: totalMutation }
-}
-
-/**
- * Читає `.n-cursor.json#coverage.classifyConfidenceThreshold` (default 1.1 — rollout mode).
- * @param {string} cwd корінь проєкту
- * @returns {Promise<number>} threshold у [0, 1.1]
- */
-async function readClassifyThreshold(cwd) {
-  try {
-    const raw = await readFile(join(cwd, '.n-cursor.json'), 'utf8')
-    const parsed = JSON.parse(raw)
-    const t = parsed?.coverage?.classifyConfidenceThreshold
-    return typeof t === 'number' && Number.isFinite(t) ? t : 1.1
-  } catch {
-    return 1.1
-  }
-}
-
-/**
- * Резолвить scope змінених файлів для `--changed`-режиму.
- *
- * Base — git merge-base поточної гілки з `main` або `origin/main`.
- * `git diff <base>` проти робочого дерева ловить committed і uncommitted однаково,
- * тож scope не залежить від того, чи крок уже закомічено.
- * @param {string} cwd корінь проєкту
- * @returns {{base: string|null, files: string[]}} base-ref і relative-posix список змінених файлів
- */
-export function resolveChangedScope(cwd) {
-  const base = resolveChangedBase(cwd)
-  return { base, files: collectChangedFilesSince(base, cwd) }
-}
-
-/**
- * Виконує coverage-pipeline: discovery провайдерів за `.n-cursor.json#rules`,
- * detect+collect для кожного, агрегація, запис COVERAGE.md.
- * При `opts.fix === true` після запису COVERAGE.md запускає агента (coverage-fix.mjs)
- * для написання тестів по вцілілих мутантах.
- * При `opts.changed === true` провайдери звужують scope до змінених від base файлів
- * для швидкого gate. Порожній scope (нема релевантних змін) — це pass (exit 0)
- * без перезапису наявного COVERAGE.md, а НЕ помилка «жодного провайдера».
- * @param {{cwd?:string, rulesDir?:string, fix?:boolean, changed?:boolean}} [opts] ін'єкція cwd/rulesDir для тестів; fix — --fix режим; changed — scope лише змінених
- * @returns {Promise<number>} exit code (0 OK, 1 коли жоден провайдер не дав даних у full-режимі)
- */
-export async function runCoverageSteps(opts = {}) {
-  const cwd = opts.cwd ?? process.cwd()
-  const rulesDir = opts.rulesDir ?? RULES_DIR
-  const config = await readNCursorConfigLite(cwd)
-  const scope = opts.changed ? resolveChangedScope(cwd) : null
-  const collectOpts = scope ? { changedFiles: scope.files, base: scope.base } : {}
-  const rows = []
-
-  for (const ruleId of config.rules) {
-    if (config.disableRules.includes(ruleId)) continue
-    const provider = await loadProvider(rulesDir, ruleId)
-    if (!provider) continue
-    if (!(await provider.detect(cwd))) continue
-    console.log(`→ ${ruleId} coverage…`)
-    rows.push(...(await provider.collect(cwd, collectOpts)))
-  }
-
-  if (rows.length === 0) {
-    // --changed: порожній scope = «нема релевантних змін» → pass, не чіпаємо COVERAGE.md.
-    if (opts.changed) {
-      console.log('✓ coverage --changed: немає змінених файлів у scope провайдерів — пропускаю')
-      return 0
-    }
-    console.error('✗ Жодного провайдера покриття не знайдено для активних правил у .n-cursor.json#rules')
-    return 1
-  }
-
-  // --changed (турнікет): рішення гейту визначає лише exit-код — vitest/Stryker кинули б помилку
-  // під час collect, якби тести/прогін упали. Тут НЕ перезаписуємо повний COVERAGE.md частковим
-  // scoped-звітом і не ганяємо LLM-класифікацію (зайвий кошт у per-step циклі).
-  if (opts.changed) {
-    console.log('✓ coverage --changed: змінені файли перевірено')
-    return 0
-  }
-
-  // LLM-класифікація survived мутантів (graceful skip без API key)
-  const allSurvived = rows.flatMap(r => r.survived ?? [])
-  let augmentedRows = rows
-  let allowedGaps = []
-  if (allSurvived.length > 0) {
-    const verdicts = await classify(allSurvived, cwd)
-    if (verdicts.length > 0) {
-      const threshold = await readClassifyThreshold(cwd)
-      const applied = applyVerdicts(rows, verdicts, threshold)
-      augmentedRows = applied.rows
-      allowedGaps = applied.allowedGaps
-    }
-  }
-
-  // Підсумок «Разом» має сенс лише коли провайдерів ≥2; для єдиного рядка він
-  // дублює його значення, тож не додаємо.
-  if (augmentedRows.filter(r => r.area !== '**Разом**').length > 1) {
-    augmentedRows.push(buildTotalsRow(augmentedRows.filter(r => r.area !== '**Разом**')))
-  }
-  const md = renderMarkdown(augmentedRows, allowedGaps)
-  // Stryker disable next-line StringLiteral: equivalent – writeFile(path, str, '') behaves identically to 'utf8' in Node/Bun
-  await writeFile(join(cwd, 'COVERAGE.md'), md, 'utf8')
-  console.log('✓ COVERAGE.md')
-
-  if (opts.fix) {
-    const { fixSurvivedMutants } = await import(new URL('../../../scripts/coverage-fix.mjs', import.meta.url).href)
-    await fixSurvivedMutants(allSurvived, cwd)
-  }
-
-  return 0
-}
-
-/**
- * CLI entrypoint для `n-cursor coverage [--fix] [--changed]`.
- * Із `--fix`: збирає метрики → запускає агента → повторно збирає метрики.
- * Без `--fix`: лише збирає метрики.
- * Із `--changed`: звужує scope до змінених від git merge-base файлів.
- * Лок охоплює кожен coverage-прогін окремо.
- * @param {{fix?:boolean, changed?:boolean}} [opts] прапори --fix / --changed
- * @returns {Promise<number>} exit code
- */
-export async function runCoverageCli(opts = {}) {
-  const code = await withLock('coverage', () => runCoverageSteps(opts))
-  if (code === 0 && opts.fix) {
-    console.log('\n♻️  Повторний coverage після агента…\n')
-    return withLock('coverage', () => runCoverageSteps({ fix: false, changed: opts.changed }))
-  }
-  return code
-}

package/scripts/coverage-classify/apply.mjs

@@ -1,67 +0,0 @@
-/**
- * Застосовує verdicts до coverage rows: фільтрує survived мутантів,
- * декрементує mutation.total на кількість allowed-gaps, повертає окремий
- * список allowedGaps для рендеру в COVERAGE.md.
- *
- * Skip rule: verdict ∈ {equivalent,defensive,glue,wrapper} AND confidence ≥ threshold.
- * Решта (включно з worth-testing і low-confidence skip-verdicts) залишаються в survived.
- */
-
-const SKIP_VERDICTS = new Set(['equivalent', 'defensive', 'glue', 'wrapper'])
-
-/**
- * Чи verdict кваліфікує мутанта як allowed-gap (виключити з Killable).
- * @param {{verdict: string, confidence: number}} verdict verdict-об'єкт
- * @param {number} threshold confidence threshold (наприклад 0.7)
- * @returns {boolean} true якщо мутант — allowed gap
- */
-export function isAllowedGap(verdict, threshold) {
-  return SKIP_VERDICTS.has(verdict.verdict) && verdict.confidence >= threshold
-}
-
-/**
- * Застосовує verdicts до coverage rows. Фільтрує `survived` за isAllowedGap,
- * зменшує `mutation.total` на скільки мутантів стало allowed-gap.
- * Не мутує вхідні дані.
- * @param {Array<{area: string, coverage: object, mutation: {caught: number, total: number}, survived?: Array<{file: string, mutants: Array<object>, exampleTest?: object|null, recommendationText?: string|null}>}>} rows вхідні рядки
- * @param {Array<{key: string, verdict: {verdict: string, confidence: number, reason: string}}>} verdicts класифіковані verdict-и
- * @param {number} threshold confidence threshold для allowed-gap
- * @returns {{rows: Array<object>, allowedGaps: Array<{file: string, mutant: object, verdict: object}>}} augmented rows + список allowed-gaps
- */
-export function applyVerdicts(rows, verdicts, threshold) {
-  const verdictByKey = new Map()
-  for (const { key, verdict } of verdicts) verdictByKey.set(key, verdict)
-
-  const allowedGaps = []
-
-  const augmentedRows = rows.map(row => {
-    const survived = row.survived ?? []
-    let skippedCount = 0
-    const remainingSurvived = []
-
-    for (const group of survived) {
-      const remainingMutants = []
-      for (const mutant of group.mutants) {
-        const key = `${group.file}:${mutant.line}:${mutant.col}:${mutant.replacement}`
-        const verdict = verdictByKey.get(key)
-        if (verdict && isAllowedGap(verdict, threshold)) {
-          allowedGaps.push({ file: group.file, mutant, verdict })
-          skippedCount += 1
-        } else {
-          remainingMutants.push(mutant)
-        }
-      }
-      if (remainingMutants.length > 0) {
-        remainingSurvived.push({ ...group, mutants: remainingMutants })
-      }
-    }
-
-    return {
-      ...row,
-      survived: remainingSurvived,
-      mutation: { ...row.mutation, total: row.mutation.total - skippedCount }
-    }
-  })
-
-  return { rows: augmentedRows, allowedGaps }
-}

package/scripts/coverage-classify/cache.mjs

@@ -1,77 +0,0 @@
-/**
- * File-hash-keyed cache для coverage-classify verdicts.
- *
- * Cache key = `<blob-hash>:<line>:<col>:<base64url(replacement)>`.
- * Blob hash рахуємо через `git hash-object <file>` (детерміновано на working tree)
- * з fallback на sha1(readFile) якщо git недоступний.
- *
- * Cache schema:
- *   { version: 1, model: string|null, entries: Record<key, { verdict, confidence, reason, suggestedTest?, classifiedAt }> }
- *
- * Інвалідація: будь-яка зміна source → новий blob-hash → cache miss → re-classify.
- */
-import { execFileSync } from 'node:child_process'
-import { createHash } from 'node:crypto'
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
-import { dirname } from 'node:path'
-
-const CACHE_VERSION = 1
-
-/**
- * Хеш контенту файла (sha1, 40 hex chars). Спочатку `git hash-object`,
- * інакше sha1 контенту.
- * @param {string} filePath абсолютний шлях до файла
- * @returns {string | null} 40-char hex hash або null якщо файл недоступний
- */
-export function deriveBlobHash(filePath) {
-  if (!existsSync(filePath)) return null
-  try {
-    return execFileSync('git', ['hash-object', filePath], { encoding: 'utf8' }).trim()
-  } catch {
-    const content = readFileSync(filePath)
-    return createHash('sha256').update(content).digest('hex')
-  }
-}
-
-/**
- * Cache-ключ для конкретного мутанта в конкретному стані файла.
- * @param {string} filePath абсолютний шлях до source файла
- * @param {{line: number, col: number, replacement: string}} mutant параметри мутанта
- * @returns {string | null} ключ або null якщо файл недоступний
- */
-export function deriveCacheKey(filePath, mutant) {
-  const blobHash = deriveBlobHash(filePath)
-  if (!blobHash) return null
-  const replacement = Buffer.from(mutant.replacement, 'utf8').toString('base64url')
-  return `${blobHash}:${mutant.line}:${mutant.col}:${replacement}`
-}
-
-/**
- * Читає cache з диска. При будь-якій проблемі (file absent, corrupt JSON,
- * schema/version mismatch, entries не object) — повертає empty cache.
- * @param {string} cachePath абсолютний шлях до cache.json
- * @returns {{version: number, model: string|null, entries: Record<string, object>}} cache
- */
-export function readCache(cachePath) {
-  const empty = { version: CACHE_VERSION, model: null, entries: {} }
-  if (!existsSync(cachePath)) return empty
-  try {
-    const data = JSON.parse(readFileSync(cachePath, 'utf8'))
-    if (data?.version !== CACHE_VERSION) return empty
-    if (!data.entries || typeof data.entries !== 'object' || Array.isArray(data.entries)) return empty
-    return data
-  } catch {
-    return empty
-  }
-}
-
-/**
- * Записує cache на диск. Створює батьківські директорії.
- * @param {string} cachePath абсолютний шлях
- * @param {{version: number, model: string|null, entries: Record<string, object>}} cache cache-об'єкт
- * @returns {void}
- */
-export function writeCache(cachePath, cache) {
-  mkdirSync(dirname(cachePath), { recursive: true })
-  writeFileSync(cachePath, `${JSON.stringify(cache, null, 2)}\n`, 'utf8')
-}

package/scripts/coverage-classify/docs/apply.md

@@ -1,206 +0,0 @@
----
-type: JS Module
-title: apply.mjs
-resource: npm/scripts/coverage-classify/apply.mjs
-docgen:
-  crc: 0f54e6a0
----
-
-Модуль `apply.mjs` із пакета `coverage-classify` відповідає за **застосування вердиктів класифікатора мутаційних розривів** до табличних coverage-рядків. Він фільтрує список «вижилих» мутантів (`survived`) у кожному рядку, ділячи їх на дві категорії:
-
-1. **Allowed gaps** — мутанти, які класифікатор позначив як `equivalent`, `defensive`, `glue` або `wrapper` з рівнем впевненості (`confidence`) не нижче встановленого порогу. Такі мутанти виключаються з підрахунку «killable» (зменшують `mutation.total`) та виносяться в окремий список для подальшого рендеру в `COVERAGE.md`.
-2. **Залишок (remaining survived)** — все, що варто тестувати (`worth-testing`), а також низько-впевнені `skip`-вердикти. Ці мутанти залишаються у вихідному `row.survived` і впливають на mutation score.
-
-Модуль **не мутує вхідні дані** (`rows`, `verdicts`) — повертає нові об'єкти. Це дозволяє безпечно використовувати його у пайплайнах, де ті ж самі рядки можуть оброблятись паралельно або кешуватись.
-
-Логіка віднімання `skippedCount` з `mutation.total` зумовлена тим, що allowed-gap-мутанти не є реальною прогалиною в покритті: вони або еквівалентні оригіналу (нічого не ламають), або захисні (стосуються неможливих гілок), або клейові/обгорткові — тобто, тестувати їх економічно невиправдано.
-
-## Експорти / API
-
-| Експорт                                    | Тип            | Призначення                                                                                          |
-| ------------------------------------------ | -------------- | ---------------------------------------------------------------------------------------------------- |
-| `isAllowedGap(verdict, threshold)`         | named function | Перевіряє, чи окремий verdict-об'єкт кваліфікує мутанта як allowed-gap.                              |
-| `applyVerdicts(rows, verdicts, threshold)` | named function | Застосовує мапу вердиктів до набору coverage-рядків і повертає augmented rows + список allowed-gaps. |
-
-Default-експорту немає. Внутрішня константа `SKIP_VERDICTS` не експортується.
-
-## Функції
-
-### `isAllowedGap(verdict, threshold)`
-
-**Сигнатура:**
-
-```js
-isAllowedGap(verdict: { verdict: string, confidence: number }, threshold: number): boolean
-```
-
-**Параметри:**
-
-- `verdict` — об'єкт із полями:
-  - `verdict` (`string`) — категорія вердикту класифікатора. Очікувані значення: `'equivalent' | 'defensive' | 'glue' | 'wrapper' | 'worth-testing'` (та потенційно інші).
-  - `confidence` (`number`) — рівень впевненості класифікатора в діапазоні `[0, 1]`.
-- `threshold` (`number`) — мінімальна впевненість, починаючи з якої skip-вердикт визнається allowed-gap (наприклад, `0.7`).
-
-**Повертає:** `boolean`. `true` — якщо `verdict.verdict` належить до `SKIP_VERDICTS` (`equivalent`, `defensive`, `glue`, `wrapper`) **і** `verdict.confidence >= threshold`. Інакше — `false`.
-
-**Side effects:** немає. Чиста функція.
-
-**Гранична поведінка:**
-
-- Низько-впевнений skip-verdict (`confidence < threshold`) → `false`, мутант залишиться як survived.
-- `worth-testing` із будь-якою впевненістю → `false`.
-- Невідома категорія, відсутня в `SKIP_VERDICTS` → `false`.
-
----
-
-### `applyVerdicts(rows, verdicts, threshold)`
-
-**Сигнатура:**
-
-```js
-applyVerdicts(
-  rows: Array<Row>,
-  verdicts: Array<{ key: string, verdict: VerdictObj }>,
-  threshold: number
-): { rows: Array<Row>, allowedGaps: Array<AllowedGap> }
-```
-
-Де:
-
-```ts
-Row = {
-  area: string,
-  coverage: object,
-  mutation: { caught: number, total: number },
-  survived?: Array<{
-    file: string,
-    mutants: Array<Mutant>,
-    exampleTest?: object | null,
-    recommendationText?: string | null
-  }>
-}
-
-Mutant = { line: number, col: number, replacement: string, ...rest }
-VerdictObj = { verdict: string, confidence: number, reason: string }
-AllowedGap = { file: string, mutant: Mutant, verdict: VerdictObj }
-```
-
-**Параметри:**
-
-- `rows` — масив coverage-рядків (один рядок на «area», тобто workspace/директорію). Кожен рядок містить агреговану статистику мутацій та опційний список `survived`-груп (згрупованих по файлу).
-- `verdicts` — масив об'єктів `{ key, verdict }`, де `key` має формат `${file}:${line}:${col}:${replacement}` і однозначно ідентифікує мутанта.
-- `threshold` — поріг впевненості (передається в `isAllowedGap`).
-
-**Повертає:** об'єкт з двома полями:
-
-- `rows` (`Array<Row>`) — нові рядки, де:
-  - `survived` містить лише ті групи й тих мутантів, які **не** є allowed-gap; порожні групи (де всі мутанти стали allowed-gap) виключаються.
-  - `mutation.total` зменшено на сумарну кількість allowed-gap-мутантів у цьому рядку (`skippedCount`).
-  - `mutation.caught`, `coverage`, `area` залишаються без змін.
-  - Усі інші поля рядка зберігаються через spread (`...row`).
-- `allowedGaps` (`Array<AllowedGap>`) — плоский список (без групування по area/file) усіх мутантів, які класифіковано як allowed-gap, разом із посиланням на файл та оригінальним verdict-об'єктом. Призначений для рендеру окремої секції в `COVERAGE.md`.
-
-**Side effects:** немає. Не мутує `rows`, `verdicts`, `verdict`-об'єкти, групи `survived`, окремих мутантів. Кожен новий об'єкт створюється через `{...row}` / `{...group, mutants: remainingMutants}`.
-
-**Алгоритм:**
-
-1. Побудувати `Map<key, verdict>` із масиву `verdicts` для O(1)-пошуку.
-2. Ініціалізувати порожній акумулятор `allowedGaps`.
-3. Для кожного `row` (через `rows.map(...)`):
-   - Прочитати `survived ?? []` (підтримка рядків без поля `survived`).
-   - Завести лічильник `skippedCount = 0` і масив `remainingSurvived`.
-   - Для кожної `group` із `survived`:
-     - Завести `remainingMutants`.
-     - Для кожного `mutant` зібрати ключ `${group.file}:${mutant.line}:${mutant.col}:${mutant.replacement}`.
-     - Знайти verdict у мапі. Якщо знайдено й `isAllowedGap(verdict, threshold)` — додати `{ file: group.file, mutant, verdict }` у `allowedGaps` та інкрементувати `skippedCount`. Інакше — додати мутанта в `remainingMutants`.
-     - Якщо `remainingMutants` непорожній — додати в `remainingSurvived` об'єкт-копію групи з оновленим списком мутантів. Порожні групи відсіюються.
-   - Повернути новий рядок: `{ ...row, survived: remainingSurvived, mutation: { ...row.mutation, total: row.mutation.total - skippedCount } }`.
-4. Повернути `{ rows: augmentedRows, allowedGaps }`.
-
-**Гранична поведінка:**
-
-- Мутант без відповідного запису у `verdicts` (verdict не знайдено в мапі) → залишається в `remainingMutants` (вважаємо «не класифіковано» → не allowed-gap).
-- `row.survived` відсутній / `undefined` → `survived` у вихідному рядку буде `[]` (порожній масив), `mutation.total` без змін.
-- Усі мутанти однієї групи стали allowed-gap → група не з'являється в `remainingSurvived`.
-- Жоден мутант не визнано allowed-gap → `allowedGaps` буде порожнім, `mutation.total` без змін.
-- `mutation.total - skippedCount` може теоретично стати від'ємним, якщо `total` був неконсистентним із кількістю survived (модуль не валідує цей інваріант, надія на коректність вхідних даних).
-
-## Залежності
-
-**Зовнішні (npm):** немає. Файл — чистий ES-модуль без імпортів.
-
-**Внутрішні:** немає. Модуль є самодостатнім listener-free helper'ом без побічних залежностей.
-
-**Runtime:** Node.js / Bun (ESM, синтаксис `export function`). Використовує стандартні структури даних `Map` та `Set` без полі­філів.
-
-**Тип-формат:** усі типи описані JSDoc-блоками (без TypeScript-файлу типів). Структури `Row`, `Mutant`, `VerdictObj` визначені неявно через JSDoc у сигнатурах.
-
-## Потік виконання / Використання
-
-Модуль є проміжною ланкою в пайплайні класифікації мутаційних прогалин у coverage-звіті:
-
-1. **Збір coverage-рядків.** Інший етап пайплайну агрегує статистику покриття й мутаційного тестування по кожній area (workspace) та формує `rows` із полями `mutation.{caught,total}` та `survived` (групи `{file, mutants[]}`).
-2. **Класифікація через LLM (або іншого класифікатора).** Для кожного survived-мутанта будується ключ `${file}:${line}:${col}:${replacement}` і отримується `verdict = { verdict, confidence, reason }`. Результат — масив `{key, verdict}`.
-3. **Виклик `applyVerdicts(rows, verdicts, threshold)`.** На цьому етапі мутанти діляться на allowed-gaps та залишок, а `mutation.total` коригується.
-4. **Рендер у `COVERAGE.md`.** Поверне́ні `rows` рендеряться у таблицю покриття; `allowedGaps` — в окрему секцію «Allowed gaps» (з причинами вердиктів).
-
-**Типовий приклад використання:**
-
-```js
-import { applyVerdicts, isAllowedGap } from './apply.mjs'
-
-const threshold = 0.7
-
-const rows = [
-  {
-    area: 'npm/foo',
-    coverage: { lines: 95.2 },
-    mutation: { caught: 18, total: 20 },
-    survived: [
-      {
-        file: 'npm/foo/src/index.mjs',
-        mutants: [
-          { line: 10, col: 5, replacement: '!=' },
-          { line: 22, col: 9, replacement: '+' }
-        ]
-      }
-    ]
-  }
-]
-
-const verdicts = [
-  {
-    key: 'npm/foo/src/index.mjs:10:5:!=',
-    verdict: { verdict: 'equivalent', confidence: 0.9, reason: 'no behavioral diff' }
-  },
-  {
-    key: 'npm/foo/src/index.mjs:22:9:+',
-    verdict: { verdict: 'worth-testing', confidence: 0.85, reason: 'real gap' }
-  }
-]
-
-const { rows: augmented, allowedGaps } = applyVerdicts(rows, verdicts, threshold)
-
-// augmented[0].mutation.total === 19  (20 - 1 allowed-gap)
-// augmented[0].survived[0].mutants має 1 елемент (другий мутант)
-// allowedGaps має 1 елемент із file: 'npm/foo/src/index.mjs'
-```
-
-**Інваріанти, на які слід зважати при змінах:**
-
-- Ключ мутанта **має точно збігатися** з ключем у `verdicts` (формат `${file}:${line}:${col}:${replacement}`). Зміна формату в одному місці ламає матчинг.
-- `mutation.caught` ніколи не змінюється — allowed-gaps вилучаються тільки з `total` (бо вони і так не були caught).
-- Не покладайтесь на стабільний порядок `allowedGaps`: він залежить від порядку `rows` і всередині — порядку груп та мутантів. Якщо потрібен детермінований ордер, сортуйте у викликачі.
-
-## Rebuild Test
-
-За цією документацією має бути можливо повністю відтворити поведінку `apply.mjs`:
-
-- Скласти `Set` SKIP_VERDICTS = `{equivalent, defensive, glue, wrapper}`.
-- Реалізувати `isAllowedGap(verdict, threshold)` як `SKIP_VERDICTS.has(verdict.verdict) && verdict.confidence >= threshold`.
-- Реалізувати `applyVerdicts(rows, verdicts, threshold)`:
-  - побудувати `Map` з `verdicts`,
-  - пройти `rows.map` з immutable-оновленням,
-  - для кожного survived-мутанта зібрати ключ за фіксованим форматом, перевірити через `isAllowedGap`, зібрати окремий список allowedGaps та зменшити `mutation.total`,
-  - відсіяти порожні групи, повернути `{rows, allowedGaps}`.
-- Не імпортувати нічого; не мутувати входи.