@nitra/cursor 3.22.0 → 3.23.1

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

@@ -0,0 +1,132 @@
+# prompt.mjs
+
+## Огляд
+
+Модуль `prompt.mjs` — це prompt-builder для скрипта `coverage-classify`, що класифікує вцілілих мутантів зі звіту Stryker через LLM. Файл експонує дві сутності:
+
+- статичний рядок `SYSTEM_PROMPT`, який описує LLM правила класифікації та формат JSON-відповіді;
+- функцію `buildUserPrompt(mutant, cwd)`, яка для кожного конкретного мутанта збирає контекстний user-prompt: фрагмент вихідного коду навколо мутації, вміст відповідного тестового файла та дату останньої git-активності.
+
+Розділення на статичний `SYSTEM_PROMPT` і динамічний `buildUserPrompt` обґрунтоване стратегією кешування промптів через Anthropic API (`cache_control: ephemeral`) — незмінна частина (системний промпт) кешується між викликами, а змінна (контекст мутанта) формується щоразу заново.
+
+Модуль не виконує жодних мережевих викликів — він лише будує текст. Виклик LLM відбувається у викликальному коді (інший модуль `coverage-classify`).
+
+## Експорти / API
+
+| Експорт                        | Тип                       | Призначення                                                                                                                                                                                                                                                     |
+| ------------------------------ | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `SYSTEM_PROMPT`                | `string` (named export)   | Статичний англомовний системний промпт для LLM-класифікатора мутантів. Містить опис п'яти можливих verdict-категорій (`worth-testing`, `equivalent`, `defensive`, `glue`, `wrapper`), JSON-схему відповіді та інструкції щодо рівня впевненості (`confidence`). |
+| `buildUserPrompt(mutant, cwd)` | `function` (named export) | Будує user-prompt для одного мутанта.                                                                                                                                                                                                                           |
+
+Внутрішня (не експортована) функція:
+
+- `extractTestTitles(content)` — допоміжна, витягує заголовки `describe/test/it` з тексту test-файла.
+
+Внутрішні константи (не експортуються):
+
+- `CONTEXT_LINES = 10` — кількість рядків контексту вище й нижче рядка мутанта при формуванні фрагмента вихідного коду.
+- `TEST_FILE_MAX_LINES = 2000` — поріг розміру test-файла у рядках; якщо більше — у промпт іде лише список title-ів, а не повний текст.
+
+## Функції
+
+### `extractTestTitles(content)`
+
+Внутрішня helper-функція для редукування довгих тестових файлів до списку заголовків.
+
+- **Сигнатура**: `extractTestTitles(content: string) => string`
+- **Параметри**:
+  - `content` — повний текст test-файла як рядок.
+- **Повертає**: рядок, де кожен запис має формат `describe: <title>` або `test: <title>` / `it: <title>`, з'єднаний через `\n`. Якщо у файлі не знайдено жодного блоку `describe`/`test`/`it` — повертає літерал `(no describe/test blocks found)`.
+- **Алгоритм**: проганяє по `content` глобальний `unicode/multiline` regex `^\s*(describe|test|it)\(['"\`](.+?)['"\`]`, що ловить початки тестових блоків з аргументом у одинарних, подвійних або зворотних лапках. Для кожного match-у формує рядок `<kind>: <title>` і додає до масиву, який в кінці зливається в один рядок.
+- **Side effects**: відсутні (чиста функція).
+- **Обмеження**: regex не аналізує AST, тому коментарі типу `// describe('foo'`) також можуть бути захоплені; для шаблонів промпту це прийнятна апроксимація.
+
+### `buildUserPrompt(mutant, cwd)`
+
+Основна публічна функція модуля. Збирає markdown-розмічений user-prompt з чотирма секціями: метаінформація про мутант, фрагмент вихідного коду, існуючі тести, дата останньої git-активності файла.
+
+- **Сигнатура**: `buildUserPrompt(mutant, cwd: string) => string`, де `mutant` має форму:
+  ```
+  {
+    file: string,         // шлях до файла відносно cwd
+    line: number,         // рядок мутації (1-based)
+    col: number,          // колонка мутації
+    mutantType: string,   // тип мутанта зі Stryker (наприклад "ConditionalExpression")
+    original: string,     // оригінальний фрагмент коду
+    replacement: string   // мутований фрагмент
+  }
+  ```
+- **Параметри**:
+  - `mutant` — об'єкт-опис мутанта, як зазначено вище.
+  - `cwd` — абсолютний шлях до кореня проєкту; використовується для побудови абсолютного шляху до файла й як `cwd` для виклику `git`.
+- **Повертає**: markdown-рядок із секціями `# Mutant`, `# Source context (±10 lines)`, `# Existing tests`, `# Recent activity`. Готовий бути переданим у поле `messages[].content` LLM-запиту.
+- **Side effects**:
+  - синхронні read-only file system операції: `existsSync`, `readFileSync` для джерельного файла й тестового файла;
+  - синхронний виклик процесу `git log -1 --format=%ar -- <absPath>` через `execFileSync` (read-only щодо git-репозиторію).
+- **Обробка помилок / graceful fallback**:
+  - якщо джерельний файл не існує — `srcContext = '(source file unavailable)'`;
+  - якщо тестовий файл не існує — `existingTests = '(no test file)'`;
+  - якщо `git` недоступний, файл untracked або команда падає — `recentActivity = '(no git history)'`. `catch`-блок мовчазний, помилка проковтується (за коментарем `git unavailable or file untracked — keep placeholder`).
+
+#### Алгоритм формування секцій
+
+1. **Абсолютний шлях**: `absPath = join(cwd, mutant.file)`.
+2. **Source context**:
+   - читає файл, розбиває на рядки;
+   - обчислює діапазон `[start, end)`, де `start = max(0, mutant.line - 1 - 10)`, `end = min(lines.length, mutant.line + 10)`;
+   - вирізає slice, додає до кожного рядка префікс `<absoluteLineNumber>: ` (1-based) і об'єднує через `\n`.
+3. **Existing tests** — шукає файл за конвенцією `dirname(absPath)/tests/<basename без .mjs>.test.mjs`:
+   - якщо файл існує і має <= 2000 рядків — вставляє повний вміст;
+   - якщо більше — викликає `extractTestTitles(content)` і вставляє лише заголовки тест-блоків.
+4. **Recent activity**: викликає `git log -1 --format=%ar -- <absPath>` з опціями `cwd`, `encoding: 'utf8'`, `stdio: ['ignore', 'pipe', 'ignore']` (stderr глушиться). Trim-ить результат; якщо він непорожній — підставляє у плейсхолдер.
+5. Повертає шаблонний рядок із усіма зібраними секціями.
+
+## Залежності
+
+### Зовнішні (Node.js builtins)
+
+- `node:child_process` — `execFileSync` для виклику `git log`. Прямий виклик бінарника `git` без shell-інтерпретації (аргументи — масив).
+- `node:fs` — `existsSync`, `readFileSync` для синхронного читання джерельних і тестових файлів.
+- `node:path` — `basename`, `dirname`, `join` для роботи зі шляхами.
+
+### Внутрішньопроєктні
+
+Модуль не імпортує жодних інших модулів проєкту і не має внутрішньопроєктних залежностей.
+
+### Очікувані виклики ззовні
+
+Файл є частиною комплекту `npm/scripts/coverage-classify/`. Сусідні модулі тієї ж теки (`index.mjs`, `apply.mjs`, `cache.mjs`, `verdict-schema.mjs`) ймовірно імпортують `SYSTEM_PROMPT` і `buildUserPrompt` для побудови запитів до LLM і подальшої обробки verdict-ів. Цей файл сам по собі нічого не виконує — він суто «бібліотечний».
+
+## Потік виконання / Використання
+
+Типовий сценарій споживання:
+
+1. Споживач (наприклад `index.mjs` у тій самій теці) імпортує:
+   ```
+   import { SYSTEM_PROMPT, buildUserPrompt } from './prompt.mjs'
+   ```
+2. Для кожного survived-мутанта зі Stryker-звіту:
+   - формує об'єкт `mutant` із полів звіту;
+   - викликає `const userPrompt = buildUserPrompt(mutant, process.cwd())`;
+   - відправляє у LLM-API два повідомлення:
+     - system: `SYSTEM_PROMPT` (з `cache_control: { type: 'ephemeral' }`),
+     - user: `userPrompt`.
+3. LLM повертає JSON-об'єкт за схемою, описаною у `SYSTEM_PROMPT`:
+   ```
+   {
+     "verdict": "worth-testing" | "equivalent" | "defensive" | "glue" | "wrapper",
+     "confidence": number,
+     "reason": string,
+     "suggestedTest": string  // тільки якщо verdict === "worth-testing"
+   }
+   ```
+4. Викликальний код парсить відповідь (валідація схеми ймовірно в `verdict-schema.mjs`) і застосовує її (`apply.mjs`).
+
+### Інваріанти й обмеження
+
+- `mutant.file` має бути шляхом відносно `cwd` — інакше абсолютний шлях буде некоректний і обидва файли (джерело й тест) випадуть у fallback-плейсхолдери.
+- Конвенція розташування тестів є жорсткою: `tests/<basename без .mjs>.test.mjs` поряд з джерельним файлом. Інші конвенції (наприклад `__tests__/` або `.spec.mjs`) не підтримуються — для них `existingTests` буде `(no test file)`.
+- Розширення `.mjs` зашите у `basename(absPath, '.mjs')`. Для файлів інших розширень (`.js`, `.ts`, `.vue`) `basename` залишить розширення в результаті, тому шлях до тестів стане некоректним.
+- `CONTEXT_LINES = 10` і `TEST_FILE_MAX_LINES = 2000` — внутрішні константи, не конфігуруються параметрами.
+- `git log` запускається синхронно — для великої кількості мутантів це може бути bottleneck.
+- Усі операції синхронні; модуль безпечний для послідовного використання, але не оптимізований під concurrent-доступ (хоча сам по собі stateless).

package/scripts/coverage-classify/docs/verdict-schema.md

@@ -0,0 +1,169 @@
+# verdict-schema.mjs
+
+## Огляд
+
+Модуль `verdict-schema.mjs` визначає контракт даних для відповіді LLM-класифікатора в межах інструменту `coverage-classify`. Класифікатор приймає рішення про те, як трактувати вцілілого мутанта (surviving mutant) після прогону мутаційного тестування: чи варто на нього писати тест, чи він поведінково еквівалентний, чи це захисна гілка для неможливого стану, чи це склейка/обгортка, що покривається інтеграційними тестами.
+
+Файл розв'язує дві задачі:
+
+1. Декларує **Zod-схему** `VerdictSchema`, якій має відповідати JSON-об'єкт-вердикт від LLM.
+2. Надає утиліту `parseVerdict`, яка приймає сирий текст відповіді LLM, витягує з нього перший знайдений JSON-блок, парсить його і валідовує за схемою.
+
+Призначення схеми — стабілізувати взаємодію з LLM: навіть якщо LLM повертає вердикт у вигляді тексту з преамбулою чи поясненнями, модуль робить «liberal-in, strict-out» — толерантно витягує JSON-острівець, а далі застосовує жорстку валідацію (категорія, межі впевненості, мінімальна осмисленість пояснення).
+
+Категорії вердикту (`verdict`):
+
+- `worth-testing` — pure logic / реальні гілки, варто писати юніт-тест.
+- `equivalent` — мутант поведінково еквівалентний оригіналу, він не killable.
+- `defensive` — гілка для impossible state (захисний код), не killable.
+- `glue` — CLI entry / обгортка `runStandardRule` тощо; покривається інтеграційними тестами.
+- `wrapper` — тонкий `spawn`/`fetch`-обгортка; покривається інтеграційними тестами.
+
+## Експорти / API
+
+Модуль експортує два символи (обидва — іменовані експорти ES modules):
+
+| Символ          | Тип                         | Призначення                                          |
+| --------------- | --------------------------- | ---------------------------------------------------- |
+| `VerdictSchema` | `ZodObject`                 | Схема валідації для verdict-об'єкта LLM.             |
+| `parseVerdict`  | `function(rawText: string)` | Парсер raw-text відповіді LLM у валідований verdict. |
+
+### `VerdictSchema`
+
+Z-об'єкт зі строго визначеними полями:
+
+- `verdict` — `z.enum(['worth-testing', 'equivalent', 'defensive', 'glue', 'wrapper'])`. Обов'язкове. Будь-яке інше значення відхиляється.
+- `confidence` — `z.number().min(0).max(1)`. Обов'язкове. Дробове число в діапазоні `[0, 1]`, де `0` — повна невпевненість, `1` — повна впевненість LLM у вердикті.
+- `reason` — `z.string().min(20).max(500)`. Обов'язкове. Текстове пояснення довжиною від 20 до 500 символів — мінімум змушує LLM аргументувати, максимум — обмежує балакучість.
+- `suggestedTest` — `z.string().max(300).optional()`. Опціональне. Текстова підказка/начерк тесту довжиною до 300 символів; за домовленістю заповнюється переважно для категорії `worth-testing`.
+
+Поля поза цим переліком не описано як заборонені на рівні схеми; за замовчуванням Zod пропускає невідомі ключі без помилки, але вони не з'являться в результаті типізації, що використовує цей модуль. Якщо в майбутньому потрібен strict-режим, його можна додати через `.strict()`.
+
+### `parseVerdict(rawText)`
+
+Високорівнева функція-фасад: «витягни JSON з тексту LLM і провалідуй».
+
+## Функції
+
+### `parseVerdict(rawText)`
+
+Сигнатура:
+
+```js
+function parseVerdict(rawText: string): {
+  verdict: 'worth-testing' | 'equivalent' | 'defensive' | 'glue' | 'wrapper',
+  confidence: number,
+  reason: string,
+  suggestedTest?: string
+}
+```
+
+Параметри:
+
+- `rawText` — `string`. Сирий текст, повернений LLM. Може містити довільний preamble/postamble навколо JSON-блоку (пояснення, markdown-загортки тощо). Очікується, що в тексті є рівно один корисний JSON-об'єкт-вердикт.
+
+Повертає:
+
+- Обʼєкт verdict, який пройшов валідацію `VerdictSchema`. Тип повернення відповідає схемі (див. вище).
+
+Side effects:
+
+- Жодних. Функція чиста: не пише в файлову систему, не звертається до мережі, не модифікує параметри.
+
+Алгоритм:
+
+1. Знайти позицію першого символу `{` через `rawText.indexOf('{')` → `jsonStart`.
+2. Знайти позицію останнього `}` через `rawText.lastIndexOf('}')` → `jsonEnd`.
+3. Якщо хоча б один з індексів дорівнює `-1` — кинути `Error('No JSON object found in LLM response')`.
+4. Інакше — вирізати підрядок `rawText.slice(jsonStart, jsonEnd + 1)` (включно з обома фігурними дужками) та віддати у `JSON.parse`.
+5. Результат парсингу передати у `VerdictSchema.parse(...)` і повернути.
+
+Виключення / помилки:
+
+- `Error('No JSON object found in LLM response')` — якщо в тексті немає жодної з фігурних дужок (`{` або `}`).
+- `SyntaxError` (від `JSON.parse`) — якщо вирізаний фрагмент не є валідним JSON. Наприклад, через зайвий текст усередині `{...}`, який LLM могла додати між дужками.
+- `ZodError` (від `VerdictSchema.parse`) — якщо JSON валідний, але не відповідає схемі: невідома категорія `verdict`, `confidence` поза `[0, 1]`, `reason` коротший за 20 символів або довший за 500, `suggestedTest` довший за 300 символів, відсутнє обов'язкове поле тощо.
+
+Поведінкові нюанси, важливі для викликача:
+
+- Стратегія «перший `{` … останній `}`» свідомо толерантна: дозволяє LLM писати щось ось так: `Here's the verdict: { ... } Hope it helps.` Однак якщо LLM повертає **кілька** JSON-обʼєктів, функція ризикує склеїти їх у невалідний фрагмент — це очікувано і впирається у валідацію JSON.
+- Функція не намагається «латати» некоректний JSON (немає trailing-comma-cleanup, немає markdown-fence-strip). Помилки прокидаються догори викликача — там і місце для retry / fallback-логіки.
+- У разі `ZodError` повідомлення зазвичай містить читабельний шлях до невалідного поля, що зручно для логування при debug LLM-промпта.
+
+## Залежності
+
+Зовнішні:
+
+- [`zod`](https://www.npmjs.com/package/zod) — рантайм-валідатор схем. Імпортується як `import { z } from 'zod'`. Версія керується кореневим `package.json` робочого простору `npm/`.
+
+Внутрішні:
+
+- Немає. Модуль не імпортує нічого з власного проєкту і не залежить від інших файлів `coverage-classify`.
+
+Стандартна бібліотека / середовище:
+
+- `JSON.parse` — глобальний API JavaScript runtime.
+- `String.prototype.indexOf` / `lastIndexOf` / `slice` — стандартні методи рядків.
+
+Цільове середовище: Node-сумісний рантайм (Node.js / Bun) із підтримкою ES Modules — файл написано як `.mjs`.
+
+## Потік виконання / Використання
+
+### Як модуль вписується в `coverage-classify`
+
+Інструмент `coverage-classify` працює за такою послідовністю (типова):
+
+1. Зчитати список вцілілих мутантів із результатів мутаційного тестування.
+2. Для кожного мутанта зібрати контекст (фрагмент коду, місце змін) та згенерувати промпт для LLM.
+3. Виконати запит до LLM і отримати raw-text відповідь.
+4. **Викликати `parseVerdict(rawText)`** із цього модуля, щоб отримати типізований verdict.
+5. Зберегти verdict у кеш / звіт (`apply.mjs`, `cache.mjs`) і застосувати дії: для `worth-testing` згенерувати TODO/тести, для решти — позначити мутант відповідною категорією.
+
+Таким чином, `verdict-schema.mjs` — це межа між «світом LLM» (нечіткий текст) і «світом інструменту» (структуровані дані).
+
+### Приклад використання
+
+```js
+import { parseVerdict, VerdictSchema } from './verdict-schema.mjs'
+
+// 1) Парсимо raw-відповідь LLM
+const rawLLM = `
+The mutant is in a defensive branch. Here is the verdict:
+{
+  "verdict": "defensive",
+  "confidence": 0.92,
+  "reason": "The condition guards an impossible state when the input list is empty.",
+  "suggestedTest": ""
+}
+Thanks!
+`
+
+try {
+  const verdict = parseVerdict(rawLLM)
+  // verdict.verdict === 'defensive'
+  // verdict.confidence === 0.92
+  console.log(verdict)
+} catch (err) {
+  // 'No JSON object found in LLM response' | SyntaxError | ZodError
+  console.error('LLM verdict invalid:', err.message)
+}
+
+// 2) Якщо в нас уже є об'єкт (наприклад, з кешу) — валідуємо безпосередньо через схему
+const cached = { verdict: 'glue', confidence: 1, reason: 'CLI entry point only, integration covers.' }
+const ok = VerdictSchema.parse(cached) // кине ZodError, якщо не відповідає
+```
+
+### Граничні випадки
+
+- Порожній рядок → `indexOf('{') === -1` → кидаємо `'No JSON object found in LLM response'`.
+- Рядок без `}` (LLM обірвалась) → `lastIndexOf('}') === -1` → та сама помилка.
+- LLM повернула markdown-fence (` ```json ... ``` `) навколо JSON → `parseVerdict` витягне саме JSON-острів між першим `{` і останнім `}`, fence ігнорується.
+- LLM повернула `confidence: 1.5` → `ZodError` (порушено `max(1)`).
+- LLM повернула `verdict: 'unknown'` → `ZodError` (не входить у `z.enum([...])`).
+- LLM повернула `reason` коротшим за 20 символів → `ZodError` (`min(20)`). Це навмисний захист від відповідей-однословів типу `"ok"`.
+
+### Рекомендації для викликача
+
+- Обгортайте виклик `parseVerdict` у `try/catch` і за помилки робіть retry з посиленим промптом (наприклад, з нагадуванням про схему) або падайте у fallback-категорію.
+- Не зберігайте у кеш `rawText` як вердикт — зберігайте лише провалідований об'єкт (результат `parseVerdict`); це підтримує інваріант «у кеші тільки валідні дані».
+- Якщо в майбутньому з'являться нові категорії — оновлюйте `z.enum` тут, інакше LLM-вердикти з новими значеннями будуть відхилятися.

package/scripts/coverage-fix-extract.mjs

@@ -0,0 +1,122 @@
+/**
+ * `n-cursor coverage-fix index|slice` — read-only витяг вцілілих мутантів із
+ * `COVERAGE.md` для скілу `n-coverage-fix`.
+ *
+ * Мотивація: `COVERAGE.md` може важити мегабайти (секція `## Вцілілі мутанти`
+ * з JSON-блоком на сотні файлів). Якщо цей файл читає LLM-оркестратор, він
+ * спалює сотні тисяч токенів лише на парсинг. Натомість важкий парсинг несе цей
+ * скрипт (для JS — мілісекунди, 0 токенів), а агенту віддається рівно потрібна
+ * порція:
+ *   - `index` — крихітний `[{file, mutants}]` для рішення про фан-аут;
+ *   - `slice --file <path>` — промпт лише для одного файлу (контекст ±3 рядки),
+ *     рівно під когнітивне навантаження одного субагента.
+ *
+ * Команда read-only: лише парсить наявний `COVERAGE.md`, нічого не мутує і не
+ * перезапускає Stryker (тож не входить у root-guard).
+ */
+import { readFile } from 'node:fs/promises'
+import { join } from 'node:path'
+
+import { buildFixPrompt } from './coverage-fix.mjs'
+
+/** Заголовок секції вцілілих мутантів у COVERAGE.md (контракт із renderMarkdown). */
+const SURVIVED_SECTION = '## Вцілілі мутанти'
+
+/**
+ * Огорожа json-блоку: ≥3 бектики, далі `json` і решта рядка до `\n`. Довжина
+ * захоплюється в групу 1 — renderMarkdown пише 3, але oxfmt підвищує до 4+, коли
+ * сам JSON-вміст містить ``` (типово для original/replacement мутантів).
+ */
+const FENCE_OPEN_RE = /(`{3,})json[^\n]*\n/
+
+/**
+ * Витягує JSON-масив вцілілих мутантів із тексту COVERAGE.md: знаходить секцію
+ * `## Вцілілі мутанти`, перший огороджений ` ```json ` блок під нею і парсить.
+ * @param {string} md повний текст COVERAGE.md
+ * @returns {import('./coverage-fix.mjs').SurvivedFileGroup[]} групи вцілілих по файлах (порожньо, якщо секції/блоку немає або JSON невалідний)
+ */
+export function parseSurvivedBlock(md) {
+  const sectionAt = md.indexOf(SURVIVED_SECTION)
+  if (sectionAt === -1) return []
+  const after = md.slice(sectionAt)
+  const open = after.match(FENCE_OPEN_RE)
+  if (!open) return []
+  const fence = open[1]
+  const bodyStart = open.index + open[0].length
+  const rest = after.slice(bodyStart)
+  // Закриття — рядок із тих самих бектиків. Усередині JSON реальних переводів
+  // рядка немає (JSON.stringify екранує їх як `\n`), тож `\n<fence>` унікально
+  // позначає кінець блоку навіть якщо значення містять бектики.
+  const closeAt = rest.indexOf(`\n${fence}`)
+  const json = closeAt === -1 ? rest : rest.slice(0, closeAt)
+  try {
+    const parsed = JSON.parse(json)
+    return Array.isArray(parsed) ? parsed : []
+  } catch {
+    return []
+  }
+}
+
+/**
+ * Читає `COVERAGE.md` із кореня проєкту і повертає структуровані групи вцілілих.
+ * @param {string} cwd корінь проєкту
+ * @returns {Promise<import('./coverage-fix.mjs').SurvivedFileGroup[]>} групи вцілілих по файлах
+ */
+export async function readSurvived(cwd) {
+  let md
+  try {
+    md = await readFile(join(cwd, 'COVERAGE.md'), 'utf8')
+  } catch {
+    return []
+  }
+  return parseSurvivedBlock(md)
+}
+
+/**
+ * Згортає групи вцілілих у компактний index `[{file, mutants}]`.
+ * @param {import('./coverage-fix.mjs').SurvivedFileGroup[]} survived групи вцілілих
+ * @returns {Array<{file:string, mutants:number}>} файл → кількість вцілілих мутантів
+ */
+export function buildIndex(survived) {
+  return survived
+    .filter(group => group && typeof group.file === 'string' && Array.isArray(group.mutants))
+    .map(group => ({ file: group.file, mutants: group.mutants.length }))
+}
+
+const USAGE = 'Usage: n-cursor coverage-fix <index | slice --file <path>>'
+
+/**
+ * CLI: `index` друкує компактний JSON-масив, `slice --file <path>` — промпт для
+ * одного файлу. Обидва read-only (читають лише COVERAGE.md).
+ * @param {string[]} args аргументи після `coverage-fix`
+ * @param {string} [cwd] корінь проєкту (ін'єкція для тестів)
+ * @returns {Promise<number>} exit code
+ */
+export async function runCoverageFixCli(args, cwd = process.cwd()) {
+  const sub = args[0]
+  const survived = await readSurvived(cwd)
+
+  if (sub === 'index') {
+    process.stdout.write(`${JSON.stringify(buildIndex(survived))}\n`)
+    return 0
+  }
+
+  if (sub === 'slice') {
+    const flagAt = args.indexOf('--file')
+    const file = flagAt === -1 ? undefined : args[flagAt + 1]
+    if (!file) {
+      console.error(USAGE)
+      return 1
+    }
+    const group = survived.find(g => g && g.file === file)
+    if (!group) {
+      console.error(`✗ Файл не знайдено серед вцілілих мутантів: ${file}`)
+      return 1
+    }
+    process.stdout.write(`${await buildFixPrompt([group], cwd)}\n`)
+    return 0
+  }
+
+  console.error(USAGE)
+  return 1
+}

package/scripts/coverage-fix.mjs

@@ -54,7 +54,7 @@ export async function fixSurvivedMutants(survived, projectRoot) {
  * @param {string} projectRoot корінь проєкту
  * @returns {Promise<string>} текст rich-промпту
  */
-async function buildFixPrompt(survived, projectRoot) {
+export async function buildFixPrompt(survived, projectRoot) {
   const sections = []
 
   for (const { file, mutants, exampleTest } of survived) {