@nitra/cursor 12.11.1 → 12.11.3

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}`.
-- Не імпортувати нічого; не мутувати входи.

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

@@ -1,207 +0,0 @@
----
-type: JS Module
-title: cache.mjs
-resource: npm/scripts/coverage-classify/cache.mjs
-docgen:
-  crc: 53b251b1
----
-
-Модуль `cache.mjs` реалізує **file-hash-keyed cache** для вердиктів класифікатора покриття мутаційного тестування (`coverage-classify`). Призначення — уникати повторної (зазвичай дорогої — через LLM) класифікації того ж самого мутанта в незмінному файлі.
-
-Ключова ідея кешу:
-
-- Ключ кешу формується з трьох компонентів:
-  1. `blob-hash` — sha1-хеш контенту source-файла (отримується через `git hash-object` з fallback на власне sha1 від `readFileSync`).
-  2. Координати мутанта в файлі: `line:col`.
-  3. `base64url` від рядка-replacement мутанта (щоб ключ був безпечним для будь-яких символів).
-- Формат ключа: `` `<blob-hash>:<line>:<col>:<base64url(replacement)>` ``.
-
-Логіка інвалідації:
-
-- Будь-яка зміна source-файла → новий `blob-hash` → старий ключ більше ніколи не співпадає → `cache miss` → мутант буде перекласифіковано.
-- Інвалідація автоматична: жодного TTL, версіонування user-input або ручного очищення не потрібно.
-
-Схема кешу на диску:
-
-```json
-{
-  "version": 1,
-  "model": "string|null",
-  "entries": {
-    "<key>": {
-      "verdict": "...",
-      "confidence": "...",
-      "reason": "...",
-      "suggestedTest": "...",
-      "classifiedAt": "..."
-    }
-  }
-}
-```
-
-Поле `version` використовується як schema-guard: при зміні константи `CACHE_VERSION` всі старі файли кешу автоматично трактуються як порожні (без помилок), що дозволяє безпечно еволюціонувати схему.
-
-## Експорти / API
-
-Модуль експортує три іменовані функції (ESM):
-
-| Функція                            | Призначення                                                                    |
-| ---------------------------------- | ------------------------------------------------------------------------------ |
-| `deriveBlobHash(filePath)`         | Обчислити sha1-хеш контенту файла.                                             |
-| `deriveCacheKey(filePath, mutant)` | Сформувати повний ключ кешу для конкретного мутанта в конкретному стані файла. |
-| `readCache(cachePath)`             | Безпечно прочитати cache з диска з порожнім fallback.                          |
-| `writeCache(cachePath, cache)`     | Записати cache на диск (з автостворенням батьківських директорій).             |
-
-Внутрішня (не експортована) константа:
-
-- `CACHE_VERSION = 1` — поточна версія schema.
-
-## Функції
-
-### `deriveBlobHash(filePath)`
-
-Обчислює 40-символьний hex sha1-хеш контенту файла.
-
-- **Сигнатура:** `deriveBlobHash(filePath: string): string | null`
-- **Параметри:**
-  - `filePath` — абсолютний шлях до source-файла.
-- **Повертає:**
-  - 40-символьний hex-рядок (sha1) — якщо файл прочитано.
-  - `null` — якщо файл не існує (`existsSync` повернув `false`).
-- **Алгоритм:**
-  1. Якщо файл відсутній — повернути `null`.
-  2. Спробувати викликати `git hash-object <file>` через `execFileSync` з кодуванням `utf8` і обрізати whitespace (`.trim()`). Це детерміністичний хеш в межах working tree; точно такий же хеш Git використовує внутрішньо для blob-ів.
-  3. Якщо `git` недоступний або кинув помилку — fallback: прочитати файл (`readFileSync`) і обчислити `createHash('sha1').update(content).digest('hex')`.
-- **Side effects:** виконує зовнішній процес `git`; читає файл (у fallback-гілці).
-- **Чому два шляхи:** `git hash-object` працює швидше для великих репозиторіїв і додає до хешу префікс `blob <size>\0` як справжній Git. Однак скрипт може бути запущений у середовищі без `git` (CI worker, контейнер) — звідси sha1-fallback. Для двох однакових файлів обидва методи дають **різні** хеші, але це **не критично**, бо ключ кешу самосумісний у межах одного запуску — головне, щоб хеш був детерміністичним для тих самих байтів.
-
-### `deriveCacheKey(filePath, mutant)`
-
-Формує ключ кешу для конкретного мутанта в конкретному стані файла.
-
-- **Сигнатура:** `deriveCacheKey(filePath: string, mutant: { line: number, col: number, replacement: string }): string | null`
-- **Параметри:**
-  - `filePath` — абсолютний шлях до source-файла, в якому міститься мутант.
-  - `mutant` — об'єкт-опис мутанта:
-    - `line: number` — номер рядка (1-based, як прийнято в Stryker/інших мутаторах).
-    - `col: number` — номер колонки.
-    - `replacement: string` — рядок-заміна, який мутатор вставляє замість оригінального коду.
-- **Повертає:**
-  - Рядок виду `` `<sha1>:<line>:<col>:<base64url>` ``.
-  - `null` — якщо `deriveBlobHash` повернув `null` (файл недоступний → ключ створити неможливо).
-- **Алгоритм:**
-  1. Отримати `blobHash` через `deriveBlobHash(filePath)`.
-  2. Якщо `null` — повернути `null` (попереджаючий контракт: caller має обробити cache-miss).
-  3. Закодувати `mutant.replacement` як `base64url` (без `=` padding і без `/`/`+`, що робить його безпечним і для filename, і для key).
-  4. Зібрати ключ template-literal-ом.
-- **Side effects:** ті ж, що й у `deriveBlobHash` (виклик `git`/`readFileSync`).
-- **Чому `base64url`:** `replacement` може містити будь-які символи (двокрапки, переноси рядків, юнікод). `base64url` гарантує однорядковий ASCII-ключ без колізій по роздільнику `:`.
-
-### `readCache(cachePath)`
-
-Безпечно читає cache з диска. Будь-яка аномалія (відсутність файла, битий JSON, чужа схема) **не кидає** помилку, а повертає порожній cache.
-
-- **Сигнатура:** `readCache(cachePath: string): { version: number, model: string | null, entries: Record<string, object> }`
-- **Параметри:**
-  - `cachePath` — абсолютний шлях до файла `cache.json`.
-- **Повертає:** об'єкт cache-схеми. Або реальні дані з диска, або **empty cache**:
-
-  ```js
-  { version: CACHE_VERSION, model: null, entries: {} }
-  ```
-
-- **Алгоритм (5 умов повернення empty):**
-  1. Файл не існує (`!existsSync(cachePath)`) → empty.
-  2. `JSON.parse` кинув виняток → empty (catch).
-  3. `data?.version !== CACHE_VERSION` (включно з `data === null`/`undefined`) → empty.
-  4. `!data.entries` → empty.
-  5. `typeof data.entries !== 'object'` або `Array.isArray(data.entries)` → empty.
-  6. Інакше повернути `data` як є.
-- **Side effects:** читає файл з диска (`readFileSync` з кодуванням `utf8`).
-- **Інваріант:** ніколи не кидає винятки — гарантовано повертає валідний cache-об'єкт.
-
-### `writeCache(cachePath, cache)`
-
-Серіалізує cache в JSON і записує на диск.
-
-- **Сигнатура:** `writeCache(cachePath: string, cache: { version: number, model: string | null, entries: Record<string, object> }): void`
-- **Параметри:**
-  - `cachePath` — абсолютний шлях, куди писати (наприклад `<repo>/.cache/coverage-classify/cache.json`).
-  - `cache` — cache-об'єкт у відповідності до schema.
-- **Повертає:** `void`.
-- **Алгоритм:**
-  1. `mkdirSync(dirname(cachePath), { recursive: true })` — гарантовано створює всі батьківські директорії; не падає, якщо вони вже існують.
-  2. `writeFileSync(cachePath, JSON.stringify(cache, null, 2) + '\n', 'utf8')` — двопробільний indent для людиночитності + trailing newline (POSIX-конвенція).
-- **Side effects:** створює директорії, перезаписує файл повністю (атомарність не гарантується — це звичайний `writeFileSync`).
-
-## Залежності
-
-Лише модулі стандартної бібліотеки Node.js (ESM):
-
-| Імпорт                                                     | Звідки               | Призначення                                                        |
-| ---------------------------------------------------------- | -------------------- | ------------------------------------------------------------------ |
-| `execFileSync`                                             | `node:child_process` | Виклик `git hash-object` як зовнішнього процесу.                   |
-| `createHash`                                               | `node:crypto`        | sha1-fallback, якщо `git` недоступний.                             |
-| `existsSync`, `mkdirSync`, `readFileSync`, `writeFileSync` | `node:fs`            | Sync-FS-операції для cache та source-файлів.                       |
-| `dirname`                                                  | `node:path`          | Виокремити батьківську директорію з cache-шляху перед `mkdirSync`. |
-
-Зовнішніх npm-залежностей **немає**. Усі імпорти — з prefix `node:` (рекомендований формат для Node.js core-модулів).
-
-Опціональна зовнішня залежність: бінарник `git` у `$PATH`. Якщо його немає — модуль автоматично переходить на sha1-fallback.
-
-## Потік виконання / Використання
-
-Типовий sequence використання у класифікаторі:
-
-1. На старті прогону: `cache = readCache(cachePath)`.
-2. Для кожного мутанта:
-   1. `key = deriveCacheKey(filePath, mutant)`.
-   2. Якщо `key === null` — пропустити (файл-джерело недоступний) або повторити пізніше.
-   3. Якщо `cache.entries[key]` існує — використати збережений verdict, **не** викликати LLM.
-   4. Інакше — викликати класифікатор (LLM/heuristic), отримати `verdict` і записати:
-      ```js
-      cache.entries[key] = { verdict, confidence, reason, suggestedTest, classifiedAt: new Date().toISOString() }
-      ```
-3. На завершенні прогону: `writeCache(cachePath, cache)`.
-
-Граничні випадки та їх обробка:
-
-- **Source файл видалили** → `deriveBlobHash` повертає `null` → `deriveCacheKey` повертає `null`. Caller повинен пропустити кешування.
-- **Git недоступний** → автоматичний fallback на sha1. Ключі будуть відрізнятися від ключів, отриманих через `git hash-object` для того ж файла. Тому при міграції оточення можливий повний cache-miss — але це безпечно (просто повторна класифікація).
-- **Cache-файл пошкоджений** → `readCache` повертає empty cache. Жодних винятків. Старий битий вміст буде перезаписаний при наступному `writeCache`.
-- **Зміна `CACHE_VERSION`** → всі попередні файли кешу мовчки трактуються як empty. Безпечний шлях для еволюції schema.
-
-Приклад мінімального використання:
-
-```js
-import { readCache, writeCache, deriveCacheKey } from './cache.mjs'
-
-const cachePath = '/abs/path/to/cache.json'
-const cache = readCache(cachePath)
-
-const key = deriveCacheKey('/abs/path/to/src/foo.js', { line: 10, col: 5, replacement: '' })
-if (key && cache.entries[key]) {
-  // Cache hit — використати готовий verdict.
-  const verdict = cache.entries[key]
-  console.log(verdict)
-} else if (key) {
-  // Cache miss — викликати класифікатор і зберегти.
-  const verdict = await classify(/* ... */)
-  cache.entries[key] = { ...verdict, classifiedAt: new Date().toISOString() }
-}
-
-writeCache(cachePath, cache)
-```
-
-## Rebuild Test
-
-Розумова перевірка: чи можна за цією документацією відтворити модуль без читання source? Так:
-
-- Заявлені 4 експорти (`deriveBlobHash`, `deriveCacheKey`, `readCache`, `writeCache`) — всі описані з сигнатурами, типами параметрів, повертанням, side effects і алгоритмом.
-- Внутрішня константа `CACHE_VERSION = 1` згадана.
-- Schema cache-файла наведена.
-- Алгоритм формування ключа (3 компоненти + base64url для replacement) пояснений однозначно.
-- Fallback-логіка `git hash-object` → `sha1(readFileSync)` описана.
-- Поведінка `readCache` при кожному типі помилки (5 пунктів) перерахована.
-- Імпорти node-core модулів перелічені з їх роллю.
-- Жодного зовнішнього npm-пакета не використано.

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

@@ -1,14 +0,0 @@
----
-type: JS Module
-title: index.mjs
-resource: npm/scripts/coverage-classify/index.mjs
-docgen:
-  crc: 06249ac8
----
-
-| Файл                                    | Тип       | Опис                                                                                                   |
-| --------------------------------------- | --------- | ------------------------------------------------------------------------------------------------------ |
-| [apply.mjs](apply.md)                   | JS Module | Модуль apply.mjs із пакета coverage-classify відповідає за \*\*застосування вердиктів класифікатора му |
-| [cache.mjs](cache.md)                   | JS Module | Модуль cache.mjs реалізує **file-hash-keyed cache** для вердиктів класифікатора покриття мутаційного   |
-| [prompt.mjs](prompt.md)                 | JS Module | Модуль prompt.mjs — це prompt-builder для скрипта coverage-classify, що класифікує вцілілих мутантів   |
-| [verdict-schema.mjs](verdict-schema.md) | JS Module | Файл надає схему VerdictSchema для валідації вердиктів LLM-класифікатора.                              |