@7n/test 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+## [0.2.0] - 2026-06-26
+
+### Changed
+
+- Міграція на чистий pi SDK: видалено прямі HTTP-виклики oMLX (`omlx.mjs`, `llm.mjs`, `models.mjs`, `omlx-trace.mjs`), весь LLM-трафік тепер іде через `@earendil-works/pi-coding-agent` via `callText` у `pi-client.mjs`. Додано опційний параметр `model` до `callText`. Моделі tier1/tier2 беруться з `N_LOCAL_MIN_MODEL`/`N_CLOUD_MIN_MODEL`.

package/README.md

@@ -0,0 +1,3 @@
+# @7n/test
+
+CLI-утиліта `@7n/test`

package/bin/n.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { run } from '../src/index.js'
+
+process.exitCode = await run(process.argv.slice(2))

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@7n/test",
+  "version": "0.2.0",
+  "description": "CLI-утиліта @7n/test",
+  "keywords": [
+    "7n",
+    "bun",
+    "cli"
+  ],
+  "homepage": "https://github.com/nitra/7n-test#readme",
+  "bugs": {
+    "url": "https://github.com/nitra/7n-test/issues"
+  },
+  "license": "ISC",
+  "author": "vitaliytv@nitralabs.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nitra/7n-test.git"
+  },
+  "bin": {
+    "n": "bin/n.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "!src/**/*.test.mjs",
+    "CHANGELOG.md",
+    "README.md",
+    "types"
+  ],
+  "type": "module",
+  "main": "./src/index.js",
+  "types": "./types/index.d.ts",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "start": "bun ./bin/n.js",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@earendil-works/pi-coding-agent": "^0.80.2",
+    "zod": "^3.23.0"
+  },
+  "engines": {
+    "bun": ">=1.3",
+    "node": ">=24"
+  }
+}

package/src/assess-need.mjs

@@ -0,0 +1,76 @@
+/**
+ * LLM assessment via pi SDK: does an uncovered file actually need unit tests?
+ * Uses callText() (no tools) for structured JSON replies.
+ */
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { callText } from './lib/pi-client.mjs'
+
+const MAX_CONTENT_BYTES = 6000
+
+const SYSTEM_PROMPT = `You are a test-need classifier for JS/TS source files.
+
+Given a source file with low test coverage, decide if unit tests are worthwhile.
+
+Reply ONLY with a JSON object (no markdown fence):
+{"needsTests": true|false, "reason": "one sentence in Ukrainian"}
+
+needsTests: false when:
+- File only contains types, interfaces, constants, or re-exports with no logic
+- Thin config or index file that just wires up other modules
+- Behavior is fully covered by integration/e2e tests (name them)
+
+needsTests: true when:
+- File contains utility functions, parsers, transformers with branches
+- Business logic with conditions or non-trivial contracts
+- Pure functions that can be unit-tested cheaply`
+
+/**
+ * @param {{file: string, pct: number}} fileInfo
+ * @param {string} dir project root
+ * @param {Function} [callTextFn] injectable for tests
+ * @returns {Promise<{file: string, pct: number, needsTests: boolean, reason: string}>}
+ */
+async function assessOne(fileInfo, dir, callTextFn) {
+  const absPath = join(dir, fileInfo.file)
+  if (!existsSync(absPath)) return { ...fileInfo, needsTests: false, reason: 'файл недоступний' }
+
+  let content = readFileSync(absPath, 'utf8')
+  if (content.length > MAX_CONTENT_BYTES) content = content.slice(0, MAX_CONTENT_BYTES) + '\n...(truncated)'
+
+  const prompt =
+    `${SYSTEM_PROMPT}\n\n` +
+    `## File: ${fileInfo.file} (current coverage: ${fileInfo.pct.toFixed(1)}%)\n\n` +
+    `\`\`\`\n${content}\n\`\`\``
+
+  try {
+    const text = await callTextFn(prompt, { cwd: dir })
+    const match = text.match(/\{[\s\S]*?"needsTests"[\s\S]*?\}/)
+    const parsed = JSON.parse(match?.[0] ?? '{}')
+    return {
+      file: fileInfo.file,
+      pct: fileInfo.pct,
+      needsTests: parsed.needsTests !== false,
+      reason: typeof parsed.reason === 'string' ? parsed.reason : ''
+    }
+  } catch {
+    return {
+      file: fileInfo.file,
+      pct: fileInfo.pct,
+      needsTests: true,
+      reason: 'оцінка не вдалась — вважаємо що потрібні тести'
+    }
+  }
+}
+
+/**
+ * Assess a list of uncovered files: do they need tests?
+ * @param {Array<{file: string, pct: number}>} files
+ * @param {string} dir project root
+ * @param {{ callText?: Function }} [opts]
+ * @returns {Promise<Array<{file: string, pct: number, needsTests: boolean, reason: string}>>}
+ */
+export async function assessNeed(files, dir, opts = {}) {
+  const callTextFn = opts.callText ?? callText
+  return Promise.all(files.map(f => assessOne(f, dir, callTextFn)))
+}

package/src/coverage/coverage.mjs

@@ -0,0 +1,315 @@
+/**
+ * Канонічна команда `n coverage`: збирає метрики покриття + мутаційного
+ * тестування з усіх провайдерів, чиє правило активне в `.n-cursor.json#rules`,
+ * агрегує та записує COVERAGE.md у корінь проєкту.
+ *
+ * Discovery провайдерів — за `.n-cursor.json#rules`: для кожного `ruleId` зі
+ * списку шукаємо `<rulesDir>/<ruleId>/coverage/coverage.mjs` і динамічно
+ * імпортуємо. Якщо файлу немає — провайдер для цього правила відсутній (skip
+ * silently, не помилка).
+ *
+ * `rulesDir` резолвиться з `node_modules/@nitra/cursor/rules` у cwd проєкту.
+ * Override — через `opts.rulesDir` у `runCoverageSteps`.
+ *
+ * Лок — прямий виклик `withLock('coverage', steps)`.
+ */
+import { existsSync } from 'node:fs'
+import { readFile, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import { pathToFileURL } from 'node:url'
+
+import { applyVerdicts } from '../coverage-classify/apply.mjs'
+import { classify } from '../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'
+
+/**
+ * Знаходить rulesDir @nitra/cursor у node_modules проєкту.
+ * @param {string} cwd корінь проєкту
+ * @returns {string|null} абсолютний шлях до rules/ або null
+ */
+function resolveDefaultRulesDir(cwd) {
+  const localPath = join(cwd, 'node_modules', '@nitra', 'cursor', 'rules')
+  if (existsSync(localPath)) return localPath
+  return null
+}
+
+/**
+ * Сума двох 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-блоком для 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` як функції.
+ * @param {string} rulesDir корінь rules/ (з @nitra/cursor або override)
+ * @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`-режиму.
+ * @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.
+ * @param {{cwd?:string, rulesDir?:string, fix?:boolean, changed?:boolean}} [opts]
+ * @returns {Promise<number>} exit code (0 OK, 1 помилка)
+ */
+export async function runCoverageSteps(opts = {}) {
+  const cwd = opts.cwd ?? process.cwd()
+  const rulesDir = opts.rulesDir ?? resolveDefaultRulesDir(cwd)
+
+  if (!rulesDir) {
+    console.error(
+      '✗ Не знайдено @nitra/cursor у node_modules. ' +
+        'Встанови @nitra/cursor як devDependency або передай rulesDir через opts.'
+    )
+    return 1
+  }
+
+  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) {
+    if (opts.changed) {
+      console.log('✓ coverage --changed: немає змінених файлів у scope провайдерів — пропускаю')
+      return 0
+    }
+    console.error('✗ Жодного провайдера покриття не знайдено для активних правил у .n-cursor.json#rules')
+    return 1
+  }
+
+  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
+    }
+  }
+
+  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('../coverage-fix.mjs', import.meta.url).href)
+    await fixSurvivedMutants(allSurvived, cwd)
+  }
+
+  return 0
+}
+
+/**
+ * CLI entrypoint для `n coverage [--fix] [--changed]`.
+ * @param {{fix?:boolean, changed?:boolean, rulesDir?:string}} [opts]
+ * @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, rulesDir: opts.rulesDir }))
+  }
+  return code
+}

package/src/coverage-classify/apply.mjs

@@ -0,0 +1,67 @@
+/**
+ * Застосовує 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/src/coverage-classify/cache.mjs

@@ -0,0 +1,77 @@
+/**
+ * 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')
+}