@nitra/cursor 1.32.0 → 1.35.1

package/rules/release/lib/change-file.mjs

@@ -0,0 +1,99 @@
+/**
+ * Один change-файл `<ws>/.changes/<timestamp>-<rand>.md`: YAML-подібний frontmatter
+ * із двома ключами (`bump`, `section`) + текст опису. Парсер мінімальний — лише ці два
+ * ключі, без зовнішніх залежностей.
+ */
+
+import { randomBytes } from 'node:crypto'
+import { existsSync } from 'node:fs'
+import { readdir, readFile } from 'node:fs/promises'
+import { join } from 'node:path'
+
+/** Дозволені semver-бампи, від найбільшого до найменшого (порядок використовується для max). */
+export const VALID_BUMPS = Object.freeze(['major', 'minor', 'patch'])
+
+/** Дозволені Keep a Changelog секції (заголовок `### {section}`). */
+export const VALID_SECTIONS = Object.freeze(['Added', 'Changed', 'Fixed', 'Removed'])
+
+const FRONTMATTER_RE = /^---\n([\s\S]*?)\n---\n([\s\S]*)$/
+
+/**
+ * @param {string} block тіло frontmatter (між `---`)
+ * @returns {Record<string, string>} пари ключ→значення
+ */
+function parseFrontmatterBlock(block) {
+  /** @type {Record<string, string>} */
+  const out = {}
+  for (const line of block.split('\n')) {
+    const idx = line.indexOf(':')
+    if (idx === -1) continue
+    out[line.slice(0, idx).trim()] = line.slice(idx + 1).trim()
+  }
+  return out
+}
+
+/**
+ * @param {string} text вміст change-файлу
+ * @returns {{ bump: string, section: string, description: string }} розпарсений запис
+ */
+export function parseChangeFile(text) {
+  const m = FRONTMATTER_RE.exec(text)
+  if (!m) throw new Error('change-файл: відсутній frontmatter `---`')
+  const fm = parseFrontmatterBlock(m[1])
+  const description = m[2].trim()
+  if (!VALID_BUMPS.includes(fm.bump)) {
+    throw new Error(`change-файл: bump має бути одним із ${VALID_BUMPS.join('|')} (отримано «${fm.bump ?? ''}»)`)
+  }
+  if (!VALID_SECTIONS.includes(fm.section)) {
+    throw new Error(`change-файл: section має бути одним із ${VALID_SECTIONS.join('|')} (отримано «${fm.section ?? ''}»)`)
+  }
+  if (!description) throw new Error('change-файл: порожній опис')
+  return { bump: fm.bump, section: fm.section, description }
+}
+
+/**
+ * @param {{ bump: string, section: string, description: string }} entry запис
+ * @returns {string} вміст change-файлу
+ */
+export function serializeChangeFile(entry) {
+  return `---\nbump: ${entry.bump}\nsection: ${entry.section}\n---\n${entry.description}\n`
+}
+
+/** Підкаталог зі change-файлами всередині workspace. */
+export const CHANGES_DIR = '.changes'
+
+/**
+ * @param {number} timestamp `Date.now()`
+ * @param {string} suffix короткий випадковий суфікс (hex)
+ * @returns {string} `<timestamp>-<suffix>.md`
+ */
+export function changeFileName(timestamp, suffix) {
+  return `${timestamp}-${suffix}.md`
+}
+
+/**
+ * Унікальне ім'я для нового change-файлу: timestamp (порядок) + rand (анти-колізія
+ * для паралельних агентів у різних worktree, що пишуть у ту саму мілісекунду).
+ * @returns {string} результат
+ */
+export function newChangeFileName() {
+  return changeFileName(Date.now(), randomBytes(3).toString('hex'))
+}
+
+/**
+ * @param {string} ws шлях workspace (відносно `cwd`)
+ * @param {string} [cwd] корінь репозиторію
+ * @returns {Promise<Array<{ file: string, entry: { bump: string, section: string, description: string } }>>} розпарсені change-файли
+ */
+export async function readChangeFiles(ws, cwd = process.cwd()) {
+  const dir = join(cwd, ws, CHANGES_DIR)
+  if (!existsSync(dir)) return []
+  const entries = await readdir(dir)
+  const names = entries.filter(n => n.endsWith('.md')).toSorted()
+  const result = []
+  for (const file of names) {
+    const text = await readFile(join(dir, file), 'utf8')
+    result.push({ file, entry: parseChangeFile(text) })
+  }
+  return result
+}

package/rules/release/lib/fallback.mjs

@@ -0,0 +1,48 @@
+/**
+ * Fallback (n-cursor-release-design рішення 3): коли в workspace є релевантні зміни,
+ * але жодного change-файлу — синтезуємо один запис із commit-subjects від останнього
+ * релізного тегу `<name>@*`. Усі git-виклики через `runGit` (ін'єкція для тестів).
+ */
+import { execFile } from 'node:child_process'
+import { promisify } from 'node:util'
+
+const execFileAsync = promisify(execFile)
+
+/**
+ * @param {string} cwd робочий каталог
+ * @returns {(args: string[]) => Promise<string | null>} тихий git-раннер (null при помилці)
+ */
+export function defaultRunGit(cwd) {
+  return async args => {
+    try {
+      const { stdout } = await execFileAsync('git', args, { cwd })
+      return stdout
+    } catch {
+      return null
+    }
+  }
+}
+
+/**
+ * @param {string} name ім'я пакета (для тегу `<name>@*`)
+ * @param {string} ws workspace (pathspec для `git log`; `.` → без обмеження шляху)
+ * @param {object} [opts] опції
+ * @param {(args: string[]) => Promise<string | null>} [opts.runGit] git-раннер
+ * @returns {Promise<{ bump: string, section: string, description: string } | null>} синтезований запис або null
+ */
+export async function synthesizeChangeFromCommits(name, ws, opts = {}) {
+  const runGit = opts.runGit ?? defaultRunGit(process.cwd())
+  const lastTagRaw = await runGit(['describe', '--tags', '--abbrev=0', '--match', `${name}@*`, 'HEAD'])
+  const lastTag = lastTagRaw?.trim()
+  // Bootstrap: якщо жодного попереднього тегу немає — перший реліз зроблено вручну;
+  // fallback-синтез не запускаємо, щоб не подвоїти bump.
+  if (!lastTag) return null
+  const pathspec = ws === '.' ? [] : ['--', `${ws}/`]
+  const logRaw = await runGit(['log', '--no-merges', '--format=%s', `${lastTag}..HEAD`, ...pathspec])
+  const subjects = (logRaw ?? '')
+    .split('\n')
+    .map(s => s.trim())
+    .filter(Boolean)
+  if (subjects.length === 0) return null
+  return { bump: 'patch', section: 'Changed', description: subjects.join('; ') }
+}

package/rules/release/release.mjs

@@ -0,0 +1,135 @@
+/**
+ * `n-cursor release` — агрегує per-workspace change-файли у version-bump + CHANGELOG,
+ * комітить, ставить тег `<name>@<version>`, видаляє use-up change-файли. Запускається
+ * у CI на `main` (n-cursor-release-design, варіант A). Сам нічого не публікує.
+ */
+import { existsSync } from 'node:fs'
+import { readFile, rm, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+
+import { getMonorepoProjectRootDirs, readPackageManifest } from '../changelog/lib/package-manifest.mjs'
+import { aggregateWorkspace, prependChangelogSection } from './lib/aggregate.mjs'
+import { CHANGES_DIR, readChangeFiles } from './lib/change-file.mjs'
+import { defaultRunGit, synthesizeChangeFromCommits } from './lib/fallback.mjs'
+
+const SEMVER_LINE_RE = /("version"\s*:\s*")[^"]*(")/
+const PY_VERSION_LINE_RE = /^(version\s*=\s*")[^"]*(")/m
+
+/**
+ * Записує нову version у маніфест, зберігаючи форматування файлу.
+ * @param {string} cwd корінь
+ * @param {import('../changelog/lib/package-manifest.mjs').PackageManifest} manifest маніфест
+ * @param {string} newVersion нова версія
+ * @returns {Promise<void>} результат
+ */
+async function writeManifestVersion(cwd, manifest, newVersion) {
+  const path = join(cwd, manifest.ws === '.' ? manifest.manifestRel : `${manifest.ws}/${manifest.manifestRel}`)
+  const text = await readFile(path, 'utf8')
+  const re = manifest.kind === 'npm' ? SEMVER_LINE_RE : PY_VERSION_LINE_RE
+  const replaced = text.replace(re, `$1${newVersion}$2`)
+  if (replaced === text) {
+    throw new Error(`release: не вдалося оновити version у ${manifest.ws}/${manifest.manifestRel} — патерн version не знайдено`)
+  }
+  await writeFile(path, replaced)
+}
+
+/**
+ * @param {string} cwd корінь
+ * @param {string} ws workspace
+ * @param {string} sectionBlock новий блок CHANGELOG
+ * @returns {Promise<void>} результат
+ */
+async function prependWorkspaceChangelog(cwd, ws, sectionBlock) {
+  const path = join(cwd, ws, 'CHANGELOG.md')
+  const existing = existsSync(path) ? await readFile(path, 'utf8') : ''
+  await writeFile(path, prependChangelogSection(existing, sectionBlock))
+}
+
+/**
+ * Зібрати change-файли workspace (явні + fallback-синтез, якщо явних нема, але є коміти).
+ * @param {string} cwd корінь
+ * @param {import('../changelog/lib/package-manifest.mjs').PackageManifest} manifest маніфест
+ * @param {(args: string[]) => Promise<string | null>} runGit git-раннер
+ * @returns {Promise<Array<{ file: string | null, entry: { bump: string, section: string, description: string } }>>} change-файли
+ */
+async function collectChangeFiles(cwd, manifest, runGit) {
+  const explicit = await readChangeFiles(manifest.ws, cwd)
+  if (explicit.length > 0) return explicit
+  if (!manifest.name) return []
+  const synthesized = await synthesizeChangeFromCommits(manifest.name, manifest.ws, { runGit })
+  if (!synthesized) return []
+  console.warn(`⚠️  ${manifest.ws}: немає change-файлів — синтезовано запис із комітів (fallback)`)
+  return [{ file: null, entry: synthesized }]
+}
+
+/**
+ * @param {object} [opts] опції
+ * @param {string} [opts.cwd] корінь
+ * @param {string} [opts.date] `YYYY-MM-DD` (за замовчуванням сьогодні)
+ * @param {(args: string[]) => Promise<string | null>} [opts.runGit] git-раннер
+ * @returns {Promise<Array<{ ws: string, name: string | null, newVersion: string }>>} зрелізовані пакети
+ */
+export async function release(opts = {}) {
+  const cwd = opts.cwd ?? process.cwd()
+  const date = opts.date ?? new Date().toISOString().slice(0, 10)
+  const runGit = opts.runGit ?? defaultRunGit(cwd)
+
+  const workspaces = await getMonorepoProjectRootDirs(cwd)
+  const subWorkspaces = workspaces.filter(w => w !== '.')
+  const isMonorepoRoot = subWorkspaces.length > 0
+
+  /** @type {Array<{ ws: string, name: string | null, newVersion: string }>} */
+  const released = []
+  const tags = []
+
+  for (const ws of workspaces) {
+    if (ws === '.' && isMonorepoRoot) continue
+    const manifest = await readPackageManifest(ws, cwd)
+    if (!manifest || !manifest.version) continue
+
+    const changeFiles = await collectChangeFiles(cwd, manifest, runGit)
+    const agg = aggregateWorkspace({ currentVersion: manifest.version, changeFiles, date })
+    if (!agg) continue
+
+    await writeManifestVersion(cwd, manifest, agg.newVersion)
+    await prependWorkspaceChangelog(cwd, ws, agg.sectionBlock)
+    for (const file of agg.consumedFiles.filter(Boolean)) {
+      await rm(join(cwd, ws, CHANGES_DIR, file))
+    }
+    released.push({ ws, name: manifest.name, newVersion: agg.newVersion })
+    if (manifest.name) tags.push(`${manifest.name}@${agg.newVersion}`)
+  }
+
+  if (released.length > 0) {
+    const subject = tags.length > 0 ? tags.join(', ') : released.map(r => `${r.ws}@${r.newVersion}`).join(', ')
+    await runGit(['add', '-A'])
+    const committed = await runGit(['commit', '-m', `release: ${subject}`])
+    if (committed === null) {
+      throw new Error('release: git commit не вдався — теги та push скасовано')
+    }
+    for (const tag of tags) {
+      await runGit(['tag', tag])
+    }
+    await runGit(['push', '--follow-tags'])
+  }
+  return released
+}
+
+/**
+ * @param {string[]} _args аргументи CLI (наразі без опцій)
+ * @returns {Promise<number>} exit-код
+ */
+export async function runReleaseCli(_args) {
+  try {
+    const released = await release()
+    if (released.length === 0) {
+      console.log('release: немає змін для релізу')
+    } else {
+      for (const r of released) console.log(`✅ ${r.name ?? r.ws}@${r.newVersion}`)
+    }
+    return 0
+  } catch (error) {
+    console.error(`❌ ${error instanceof Error ? error.message : String(error)}`)
+    return 1
+  }
+}

package/rules/test/coverage/coverage.mjs

@@ -13,10 +13,12 @@
  * specs/2026-05-24-coverage-rule-design.md).
  */
 import { existsSync } from 'node:fs'
-import { writeFile } from 'node:fs/promises'
+import { readFile, writeFile } from 'node:fs/promises'
 import { dirname, join } from 'node:path'
 import { fileURLToPath, pathToFileURL } from 'node:url'
 
+import { applyVerdicts } from '../../../scripts/coverage-classify/apply.mjs'
+import { classify } from '../../../scripts/coverage-classify/index.mjs'
 import { readNCursorConfigLite } from '../../../scripts/lib/read-n-cursor-config-lite.mjs'
 import { withLock } from '../../../scripts/utils/with-lock.mjs'
 
@@ -72,11 +74,14 @@ export function formatScore({ caught, total }) {
  * Рендерить таблицю покриття + мутаційного тестування як Markdown.
  * Якщо будь-який рядок містить непустий `survived`, додає секцію
  * `## Вцілілі мутанти` з JSON-блоком для `/n-fix-tests`.
+ * Якщо `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) {
+export function renderMarkdown(rows, allowedGaps = []) {
   const lines = [
     '# Coverage',
     '',
@@ -115,6 +120,29 @@ export function renderMarkdown(rows) {
     }
   }
 
+  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', '')
+    lines.push(`> LLM-класифікатор виключив ${allowedGaps.length} survived мутант(ів) зі знаменника mutation score.`)
+    lines.push('> Категорії: 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('|', '\\|').replaceAll('\n', ' ')
+        lines.push(
+          `| ${mutant.line} | \`${mutant.original}\` → \`${mutant.replacement}\` | ${verdict.verdict} | ${verdict.confidence.toFixed(2)} | ${sanitizedReason} |`
+        )
+      }
+    }
+  }
+
   return `${lines.join('\n')}\n`
 }
 
@@ -152,6 +180,22 @@ function buildTotalsRow(rows) {
   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
+  }
+}
+
 /**
  * Виконує coverage-pipeline: discovery провайдерів за `.n-cursor.json#rules`,
  * detect+collect для кожного, агрегація, запис COVERAGE.md.
@@ -180,14 +224,31 @@ export async function runCoverageSteps(opts = {}) {
     return 1
   }
 
-  rows.push(buildTotalsRow(rows))
-  const md = renderMarkdown(rows)
+  // LLM-класифікація survived мутантів (graceful skip без API key)
+  const allSurvived = rows.flatMap(r => r.survived ?? [])
+  let augmentedRows = rows
+  let allowedGaps = []
+  if (allSurvived.length > 0) {
+    const verdicts = await classify(allSurvived, cwd)
+    if (verdicts.length > 0) {
+      const threshold = await readClassifyThreshold(cwd)
+      const applied = applyVerdicts(rows, verdicts, threshold)
+      augmentedRows = applied.rows
+      allowedGaps = applied.allowedGaps
+    }
+  }
+
+  // Підсумок «Разом» має сенс лише коли провайдерів ≥2; для єдиного рядка він
+  // дублює його значення, тож не додаємо.
+  if (augmentedRows.filter(r => r.area !== '**Разом**').length > 1) {
+    augmentedRows.push(buildTotalsRow(augmentedRows.filter(r => r.area !== '**Разом**')))
+  }
+  const md = renderMarkdown(augmentedRows, allowedGaps)
   // Stryker disable next-line StringLiteral: equivalent – writeFile(path, str, '') behaves identically to 'utf8' in Node/Bun
   await writeFile(join(cwd, 'COVERAGE.md'), md, 'utf8')
   console.log('✓ COVERAGE.md')
 
   if (opts.fix) {
-    const allSurvived = rows.flatMap(r => r.survived ?? [])
     // eslint-disable-next-line no-unsanitized/method -- шлях відносний до пакету, не user-input
     const { fixSurvivedMutants } = await import(new URL('../../../scripts/coverage-fix.mjs', import.meta.url).href)
     await fixSurvivedMutants(allSurvived, cwd)

package/rules/test/js/no-relative-fs-path.mjs

@@ -145,7 +145,7 @@ function extractFsFunctionName(callee) {
 /**
  * Чи файл — JS-тест (`*.test.mjs` / `*.test.js`).
  * @param {string} absPath абсолютний шлях
- * @returns {boolean}
+ * @returns {boolean} true якщо файл є тестом
  */
 function isTestFile(absPath) {
   const name = basename(absPath)
@@ -187,7 +187,7 @@ function findOffendersInBody(body) {
  */
 function computeLineOffsets(body) {
   const offsets = [0]
-  for (let i = 0; i < body.length; i += 1) {
+  for (let i = 0; i < body.length; i++) {
     if (body[i] === '\n') offsets.push(i + 1)
   }
   return offsets
@@ -202,7 +202,7 @@ function offsetToLineFromCache(offsets, offset) {
   let lo = 0
   let hi = offsets.length - 1
   while (lo < hi) {
-    const mid = (lo + hi + 1) >>> 1
+    const mid = Math.floor((lo + hi + 1) / 2)
     if (offsets[mid] <= offset) lo = mid
     else hi = mid - 1
   }

package/scripts/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/scripts/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('sha1').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')
+}