@nitra/cursor 3.21.1 → 3.23.0

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

@@ -0,0 +1,202 @@
+# apply.mjs
+
+## Огляд
+
+Модуль `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

@@ -0,0 +1,203 @@
+# cache.mjs
+
+## Огляд
+
+Модуль `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

@@ -0,0 +1,218 @@
+# `coverage-classify/index.mjs`
+
+## Огляд
+
+Модуль `coverage-classify/index.mjs` — це **публічна точка входу** (Public API) класифікатора survived-мутантів за допомогою Claude API від Anthropic. Він відповідає за оркестрацію LLM-класифікації мутантів, які пережили mutation-testing раунд (тобто не були вбиті жодним тестом), і повертає для кожного з них вердикт у форматі `{ verdict, confidence, reason, suggestedTest? }`.
+
+Призначення модуля — допомогти автоматичним інструментам типу `/n-coverage-fix` ухвалювати рішення, чи варто дописувати тест на конкретний survived-мутант, чи можна його ігнорувати як equivalent / not-worth-testing.
+
+Ключові архітектурні характеристики:
+
+- **Graceful degradation:** відсутність змінної `ANTHROPIC_API_KEY` або непрацездатний dynamic import пакета `@anthropic-ai/sdk` не приводить до краху — функція мовчки повертає порожній масив `[]`, попередньо вивівши попередження у `console.warn`.
+- **Persistent cache:** результати класифікації кешуються на диск через утиліти з `./cache.mjs`. При зміні `MODEL` кеш повністю інвалідується (entries чистяться, поле `model` оновлюється). Це гарантує консистентність вердиктів між запусками за умови незмінного контексту мутанта.
+- **Prompt caching на стороні API:** системний промпт передається з `cache_control: { type: 'ephemeral' }` — усі мутанти одного прогону reuse кешований префікс на стороні Anthropic API (економія токенів).
+- **Retry з експоненційним backoff:** кожен мутант отримує до `MAX_RETRIES + 1 = 3` спроб; між спробами — затримка `retryDelayMs * 2 ** attempt`. Після вичерпання спроб — повертається **conservative fallback** `worth-testing/confidence=0`, щоб не втратити мутант з виду.
+
+Модуль не виконує мережевих викликів самостійно — він делегує їх в `client.messages.create(...)` (за замовчуванням це інстанс `new Anthropic()` з SDK).
+
+## Експорти / API
+
+| Експорт    | Тип      | Опис                                                                                             |
+| ---------- | -------- | ------------------------------------------------------------------------------------------------ |
+| `classify` | function | Іменований async-експорт. Класифікує всіх survived-мутантів і повертає масив `{ key, verdict }`. |
+
+Інші ідентифікатори файлу (`MODEL`, `MAX_RETRIES`, `DEFAULT_RETRY_DELAY_MS`, `FALLBACK_VERDICT`, `classifyOne`) — **внутрішні**, не експортуються.
+
+### Сигнатура `classify`
+
+```js
+export async function classify(survived, cwd, opts = {})
+```
+
+**Параметри:**
+
+- `survived` — `Array<{ file: string, mutants: Array<object>, exampleTest?: object|null, recommendationText?: string|null }>` — список survived-груп. Структура аналогічна до використовуваної в `COVERAGE.md` (звіт mutation-testing). Кожна група відповідає одному файлу та містить масив мутантів.
+- `cwd` — `string` — абсолютний шлях кореня проєкту. Використовується для:
+  - формування дефолтного шляху кешу (`<cwd>/npm/reports/coverage-classify.cache.json`);
+  - резолвінгу шляхів до файлів-джерел мутантів (для побудови юзер-промпта та cache key).
+- `opts` — `{ cachePath?: string, client?: object, retryDelayMs?: number }` — опціональні ін'єкції для тестування:
+  - `cachePath` — кастомний шлях до файлу кешу.
+  - `client` — підставний Anthropic SDK client (для unit-тестів без реальних мережевих викликів). Має мати метод `messages.create(...)`.
+  - `retryDelayMs` — базова затримка для exp-backoff у мс. `0` фактично вимикає sleep між retries (зручно для тестів).
+
+**Повертає:** `Promise<Array<{ key: string, verdict: object }>>`
+
+- `key` — рядок формату `<file>:<line>:<col>:<replacement>`, який однозначно ідентифікує мутант для зовнішнього коду.
+- `verdict` — об'єкт з полями `{ verdict, confidence, reason, suggestedTest? }` (формат описаний у `./verdict-schema.mjs`).
+
+При відсутності API-ключа або SDK — повертає `[]`.
+
+## Функції
+
+### `classify(survived, cwd, opts)` — публічна
+
+**Сигнатура:** `async function classify(survived, cwd, opts = {}) -> Promise<Array<{key, verdict}>>`
+
+**Параметри:** див. розділ «Експорти / API» вище.
+
+**Повертає:** `Promise<Array<{ key: string, verdict: object }>>` — плаский список вердиктів по всіх мутантах усіх груп (порядок: group-by-group, mutant-by-mutant у межах групи).
+
+**Кроки виконання (orchestration):**
+
+1. Резолвить `cachePath` (дефолт: `<cwd>/npm/reports/coverage-classify.cache.json`) та `retryDelayMs` (дефолт: `DEFAULT_RETRY_DELAY_MS = 1000`).
+2. Перевіряє `env.ANTHROPIC_API_KEY`. Якщо відсутній — `console.warn` + `return []`.
+3. Виконує `await import('@anthropic-ai/sdk')`. Якщо пакет не встановлено — `console.warn` + `return []`.
+4. Створює клієнт: `opts.client ?? new Anthropic()`.
+5. Завантажує кеш через `readCache(cachePath)`. Якщо `cache.model !== MODEL` — повністю чистить `cache.entries` і виставляє `cache.model = MODEL` (інвалідація при зміні моделі).
+6. Ітерує `survived.mutants`:
+   - Будує `lookupKey = "<group.file>:<line>:<col>:<replacement>"`.
+   - Обчислює `cacheKey = deriveCacheKey(join(cwd, group.file), mutant)`.
+   - Якщо в кеші є запис — повертає його (нормалізуючи поля, опціонально розгортаючи `suggestedTest`).
+   - Інакше викликає `classifyOne(client, group, mutant, cwd, retryDelayMs)` і записує результат у `cache.entries[cacheKey]` з полем `classifiedAt: new Date().toISOString()` (якщо `cacheKey` truthy).
+7. Зберігає кеш на диск через `writeCache(cachePath, cache)`.
+8. Повертає накопичений `verdicts`.
+
+**Side effects:**
+
+- **Disk I/O:** читання і запис файлу кешу (`<cwd>/npm/reports/coverage-classify.cache.json` за замовчуванням).
+- **Мережа:** виклики `client.messages.create(...)` до Anthropic API (через делегування в `classifyOne`).
+- **stdout/stderr:** `console.warn(...)` при відсутності ключа / SDK / при фатальних retry-фейлах окремих мутантів.
+- **Час:** функція **очікує** мережеві запити послідовно (no parallelism між мутантами) — у гіршому випадку загальна тривалість = `N × (MAX_RETRIES+1) × API_latency + sum(backoff)`.
+- **Стан системи:** мутації `cache` на місці (об'єкт переписується), потім дамп на диск.
+
+### `classifyOne(client, group, mutant, cwd, retryDelayMs)` — внутрішня
+
+**Сигнатура:** `async function classifyOne(client, group, mutant, cwd, retryDelayMs) -> Promise<object>`
+
+**Параметри:**
+
+- `client` — `{ messages: { create: Function } }` — Anthropic SDK client (реальний або mock).
+- `group` — `{ file: string }` — група для контексту (з неї потрібно лише `.file` — повний шлях до файлу-джерела).
+- `mutant` — `object` — дані мутанта (передаються в `buildUserPrompt` як `{ ...mutant, file: group.file }`).
+- `cwd` — `string` — корінь проєкту, потрібний для resolving шляхів у `buildUserPrompt`.
+- `retryDelayMs` — `number` — базова затримка для exp-backoff (`0` у тестах вимикає sleep).
+
+**Повертає:** `Promise<object>` — розпарсений вердикт (через `parseVerdict(text)`) або копія `FALLBACK_VERDICT`.
+
+**Кроки виконання:**
+
+1. Будує юзер-промпт: `userPrompt = buildUserPrompt({ ...mutant, file: group.file }, cwd)`.
+2. Цикл `for (attempt = 0; attempt <= MAX_RETRIES; attempt++)`:
+   - Виконує `client.messages.create({ model: MODEL, max_tokens: 1024, system: [{ type:'text', text: SYSTEM_PROMPT, cache_control:{ type:'ephemeral' } }], messages: [{ role:'user', content: userPrompt }] })`.
+   - Дістає текст з `response?.content?.[0]?.text ?? ''`.
+   - Повертає `parseVerdict(text)`. Якщо `parseVerdict` кидає — це впаде як виключення і потрапить в `catch` цієї ж ітерації (тобто буде ще одна retry-спроба).
+3. На `catch`: запам'ятовує `lastError`. Якщо `attempt < MAX_RETRIES && retryDelayMs > 0` — `await setTimeout(retryDelayMs * 2 ** attempt)`.
+4. Після вичерпання спроб: `console.warn` з деталями (file:line:col, кількість спроб, повідомлення останньої помилки) і `return { ...FALLBACK_VERDICT }` (копія, щоб уникнути shared mutation на константі).
+
+**Side effects:**
+
+- Мережевий виклик до Anthropic API (1..MAX_RETRIES+1 разів).
+- `setTimeout` з `node:timers/promises` (async sleep).
+- `console.warn` при фатальному фейлі.
+
+## Залежності
+
+### Внутрішні (relative imports)
+
+| Шлях                   | Що використовується                         | Призначення                                                                                                |
+| ---------------------- | ------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| `./cache.mjs`          | `deriveCacheKey`, `readCache`, `writeCache` | Робота з персистентним кешем класифікацій (deriving детермінованого ключа з мутанта + читання/запис JSON). |
+| `./prompt.mjs`         | `buildUserPrompt`, `SYSTEM_PROMPT`          | Побудова промптів для LLM: системний (статичний, кешується) та юзер-промпт (динамічний, per-mutant).       |
+| `./verdict-schema.mjs` | `parseVerdict`                              | Парсинг та валідація JSON-відповіді LLM у структурований об'єкт вердикту.                                  |
+
+### Зовнішні
+
+| Пакет/модуль           | Що використовується          | Як підключено                                                                                           |
+| ---------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------- |
+| `node:path`            | `join`                       | Статичний `import`. Збирання шляхів до cache file та source file.                                       |
+| `node:process`         | `env`                        | Статичний `import`. Читання `ANTHROPIC_API_KEY`.                                                        |
+| `node:timers/promises` | `setTimeout`                 | Статичний `import`. Async sleep для exp-backoff між retries.                                            |
+| `@anthropic-ai/sdk`    | `Anthropic` (default export) | **Dynamic** `await import(...)` всередині `classify` — graceful degradation, якщо пакет не встановлено. |
+
+### Зовнішні артефакти середовища
+
+- **Змінна оточення `ANTHROPIC_API_KEY`** — обов'язкова. Без неї модуль не робить мережевих викликів.
+- **Файл кешу** — за замовчуванням `<cwd>/npm/reports/coverage-classify.cache.json`. Структура: `{ model: string, entries: { [cacheKey]: { verdict, confidence, reason, suggestedTest?, classifiedAt } } }`.
+
+### Константи модуля
+
+| Константа                | Значення                                                     | Призначення                                                                 |
+| ------------------------ | ------------------------------------------------------------ | --------------------------------------------------------------------------- |
+| `MODEL`                  | `'claude-sonnet-4-6'`                                        | ID моделі Anthropic для класифікації. Зміна → автоматична інвалідація кешу. |
+| `MAX_RETRIES`            | `2`                                                          | Кількість **повторних** спроб (всього спроб: `MAX_RETRIES + 1 = 3`).        |
+| `DEFAULT_RETRY_DELAY_MS` | `1000`                                                       | Базова затримка для exp-backoff (мс). Реальні delays: 1000, 2000, 4000.     |
+| `FALLBACK_VERDICT`       | `{ verdict: 'worth-testing', confidence: 0, reason: '...' }` | Консервативний вердикт при фатальному фейлі (мутант ще не відкидається).    |
+
+## Потік виконання / Використання
+
+### Типовий сценарій виклику
+
+Модуль викликається з вищерівневого pipeline (наприклад, `/n-coverage-fix` або інший CLI поверх mutation-testing звіту):
+
+```js
+import { classify } from '<repo>/npm/scripts/coverage-classify/index.mjs'
+
+// survived зазвичай парситься з COVERAGE.md
+const survived = [
+  {
+    file: 'src/utils/foo.mjs',
+    mutants: [
+      { line: 10, col: 5, replacement: '=== 0', original: '!== 0', mutator: 'EqualityOperator' }
+      // ...
+    ],
+    exampleTest: null,
+    recommendationText: null
+  }
+  // ...
+]
+
+const verdicts = await classify(survived, process.cwd())
+
+for (const { key, verdict } of verdicts) {
+  if (verdict.verdict === 'worth-testing' && verdict.confidence > 0.5) {
+    // дописати тест
+  }
+}
+```
+
+### Стани виходу та граничні випадки
+
+| Стан                                                        | Поведінка                                                                            |
+| ----------------------------------------------------------- | ------------------------------------------------------------------------------------ |
+| `ANTHROPIC_API_KEY` не виставлений                          | `console.warn` + `return []` (порожній масив, не помилка).                           |
+| Пакет `@anthropic-ai/sdk` не встановлено                    | `console.warn` + `return []`.                                                        |
+| Кеш hit для мутанта                                         | Мережевий виклик не виконується, повертається cached verdict.                        |
+| Кеш miss, успішна класифікація                              | Виклик API, парсинг, запис у кеш, push у verdicts.                                   |
+| Кеш miss, всі retry-спроби впали                            | `console.warn` з деталями + `FALLBACK_VERDICT` push у verdicts (мутант не пропадає). |
+| Зміна `MODEL` у коді                                        | На наступному запуску `cache.entries` повністю обнуляється.                          |
+| `cacheKey === null/undefined` (наприклад, неможливо derive) | Класифікація виконується, але **не** кешується (запис у кеш пропускається).          |
+
+### Послідовність всередині одного прогону (timeline)
+
+1. Читання `survived` (відповідальність caller'а).
+2. `classify(...)` запускається → preflight перевірки (API key, SDK).
+3. Завантаження дискового кешу → можливе очищення при зміні моделі.
+4. **Послідовно** (не паралельно) для кожного `(group, mutant)`:
+   - Cache lookup (за `cacheKey`).
+   - Якщо miss — `classifyOne` з retry-логікою.
+   - Запис у кеш-об'єкт у пам'яті.
+5. Після обходу всіх мутантів — атомарний `writeCache` на диск.
+6. Повернення `verdicts` caller'у.
+
+### Особливості та інваріанти
+
+- **Послідовність викликів API:** немає паралелізму між мутантами. Це навмисно — обмеження по rate-limits Anthropic API та для стабільної взаємодії з prompt cache.
+- **Prompt cache reuse:** оскільки системний промпт ідентичний для всіх мутантів і помічений `cache_control: ephemeral`, Anthropic API повторно використовує кешований префікс — суттєва економія input-токенів на великих прогонах.
+- **Ідемпотентність:** повторний запуск з тим же `cachePath` і незмінним `survived` дає той же `verdicts` без додаткових мережевих викликів (повний cache hit).
+- **Conservative fallback:** при фейлі класифікації мутант **не** відкидається — він отримує `worth-testing/confidence=0`, що змушує caller свідомо вирішувати, чи приймати такий вердикт. Це усуває ризик «непомітної втрати» мутанта через мережеву помилку.
+- **Defensive copy fallback:** повертається `{ ...FALLBACK_VERDICT }`, а не сам об'єкт — щоб caller'и не могли випадково замутувати константу.
+
+### Тестування
+
+Для unit-тестів зручно ін'єктувати:
+
+- `opts.client = { messages: { create: async () => ({ content: [{ text: '...' }] }) } }` — підставний клієнт.
+- `opts.cachePath = '/tmp/test-cache.json'` — ізольований кеш.
+- `opts.retryDelayMs = 0` — миттєві retries без `setTimeout`-блокувань.
+
+Файл `index.mjs` спроєктований так, що жодних інших залежностей мокати **не потрібно** — `cache.mjs`/`prompt.mjs`/`verdict-schema.mjs` мають детерміновану поведінку для тестів.