@7n/test 0.14.5 → 0.15.0

package/src/coverage/storybook-mutation-llm.mjs

@@ -0,0 +1,180 @@
+/**
+ * LLM-джерело мутантів для Storybook mutation executor-а (storybook-mutation.mjs) —
+ * Mutahunter/Meta-ACH-патерн: LLM лише ПРОПОНУЄ context-aware bug-like мутанти
+ * (off-by-one, підмінені fallback-значення, переплутані аргументи — те, чого
+ * детерміновані оператори виразити не можуть), а вбиває/милує так само лише
+ * реальний browser-mode прогін у executor-і. Жодного LLM-суддівства pass/fail.
+ *
+ * Кожна пропозиція жорстко валідується перед прийняттям: рядок існує і покритий
+ * сторі, `original` — точний підрядок цього рядка, а мутований код парситься
+ * (`parseAst`) — синтаксично невалідні пропозиції відкидаються (інакше зламаний
+ * компайл рахувався б як killed і дуто підвищував score, патерн LLMorpheus).
+ *
+ * Graceful degradation: будь-яка помилка LLM-виклику (нема API-ключа, мережа)
+ * дає `[]` з одноразовим попередженням — детерміновані мутанти працюють далі.
+ * Opt-out: env `N_7N_TEST_NO_LLM_MUTANTS=1`.
+ */
+import { env } from 'node:process'
+import { parseAst } from 'rollup/parseAst'
+import { startChain } from '@7n/llm-lib/chain'
+import { budgetFor } from '@7n/llm-lib/prompt-budget'
+
+import { callText } from '../lib/llm.mjs'
+import { extractMutableCode } from './storybook-mutation.mjs'
+
+/** LLM-мутанти сортуються ПІСЛЯ детермінованих тірів 1–5 (власна стеля — не конкурують). */
+const LLM_TIER = 6
+const MAX_PROPOSALS = 6
+const JSON_ARRAY_RE = /\[[\s\S]*\]/
+
+const SYSTEM_PROMPT = `You are a mutation-testing expert. Propose realistic, bug-like mutants for the JavaScript code below — the kind of subtle bugs a developer could actually introduce.
+
+Reply ONLY with a JSON array (no markdown fence):
+[{"line": <number>, "original": "<exact substring of that line>", "replacement": "<text>", "category": "<short-kebab-case>", "reason": "<одне речення українською>"}]
+
+Rules:
+- line: 1-based line number as shown in the numbered code
+- original MUST be an EXACT substring of that line (long enough to locate unambiguously)
+- replacement must differ from original and keep the file syntactically valid
+- prefer bugs that simple operator swaps cannot express: off-by-one in slice/index bounds, wrong default or fallback value, swapped call arguments, wrong property name, inverted early-return condition, dropped await
+- do NOT mutate imports, comments, or purely cosmetic strings
+- only mutate lines marked as covered
+- at most ${MAX_PROPOSALS} proposals, most bug-likely first`
+
+/**
+ * Нумерує рядки коду для промпта (absolute line numbers повного файлу).
+ * @param {string} code вміст script-блоку
+ * @param {number} startLine 1-based номер першого рядка блоку в повному файлі
+ * @returns {string} код із префіксами номерів рядків
+ */
+function numberLines(code, startLine) {
+  return code
+    .split('\n')
+    .map((l, i) => `${startLine + i}: ${l}`)
+    .join('\n')
+}
+
+/**
+ * Валідує одну LLM-пропозицію і переводить її у shape мутанта executor-а.
+ * @param {{line?: unknown, original?: unknown, replacement?: unknown, category?: unknown}} p пропозиція LLM
+ * @param {string[]} sourceLines рядки повного файлу
+ * @param {number[]} lineOffsets offset початку кожного рядка у повному файлі
+ * @param {Set<number>} coveredLines покриті сторі рядки
+ * @returns {{line: number, col: number, mutantType: string, original: string, replacement: string, start: number, end: number, text: string, tier: number} | null} мутант або null (невалідна пропозиція)
+ */
+function validateProposal(p, sourceLines, lineOffsets, coveredLines) {
+  if (!p || typeof p !== 'object') return null
+  const { line, original, replacement } = p
+  if (!Number.isInteger(line) || line < 1 || line > sourceLines.length) return null
+  if (!coveredLines.has(line)) return null
+  if (typeof original !== 'string' || original.length === 0) return null
+  if (typeof replacement !== 'string' || replacement === original) return null
+
+  const lineText = sourceLines[line - 1]
+  const col = lineText.indexOf(original)
+  if (col === -1) return null
+
+  const start = lineOffsets[line - 1] + col
+  return {
+    line,
+    col,
+    mutantType: typeof p.category === 'string' && p.category ? `llm:${p.category}` : 'llm:proposed',
+    original,
+    replacement,
+    start,
+    end: start + original.length,
+    text: replacement,
+    tier: LLM_TIER
+  }
+}
+
+/**
+ * Чи мутований файл лишається синтаксично валідним (у скоупі script-блоку).
+ * @param {string} file відносний шлях файлу
+ * @param {string} source повний вміст файлу
+ * @param {{start: number, end: number, text: string}} mutant мутант для приміряння
+ * @returns {boolean} true, якщо parseAst бере мутований script-блок
+ */
+function staysParseable(file, source, mutant) {
+  const mutated = source.slice(0, mutant.start) + mutant.text + source.slice(mutant.end)
+  const extracted = extractMutableCode(file, mutated)
+  if (!extracted) return false
+  try {
+    parseAst(extracted.code)
+    return true
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Пропонує LLM-мутанти для одного файлу: один callText-виклик (окремий chain),
+ * парс JSON-відповіді, жорстка валідація кожної пропозиції (рядок/підрядок/
+ * покриття/синтаксис). Кидає помилки LLM-виклику нагору — graceful-обгортка
+ * (warn + []) живе на боці виклику (defaultRunner у js-collector.mjs).
+ * @param {object} opts опції
+ * @param {string} opts.file відносний шлях файлу
+ * @param {string} opts.source повний вміст файлу
+ * @param {Set<number>} opts.coveredLines покриті сторі рядки (1-indexed)
+ * @param {string} opts.cwd робоча директорія для LLM-session/chain
+ * @param {typeof callText} [opts.callTextFn] LLM-колер (ін'єкція для тестів)
+ * @param {typeof startChain} [opts.makeChain] фабрика ланцюжка (ін'єкція для тестів)
+ * @returns {Promise<Array<object>>} валідні мутанти у shape generateMutants (може бути порожнім)
+ */
+export async function proposeLlmMutants(opts) {
+  const { file, source, coveredLines, cwd, callTextFn = callText, makeChain = startChain } = opts
+  if (env.N_7N_TEST_NO_LLM_MUTANTS) return []
+
+  const extracted = extractMutableCode(file, source)
+  if (!extracted) return []
+
+  const sourceLines = source.split('\n')
+  const lineOffsets = []
+  let offset = 0
+  for (const l of sourceLines) {
+    lineOffsets.push(offset)
+    offset += l.length + 1
+  }
+
+  // 1-based номер першого рядка script-блоку в повному файлі
+  const blockStartLine = source.slice(0, extracted.offset).split('\n').length
+  const covered = [...coveredLines].toSorted((a, b) => a - b).join(', ')
+
+  const prompt = [
+    SYSTEM_PROMPT,
+    '',
+    `## File: ${file}`,
+    `Covered lines: ${covered}`,
+    '',
+    '```js',
+    numberLines(extracted.code, blockStartLine),
+    '```'
+  ].join('\n')
+
+  const chain = makeChain({ kind: 'sb-llm-mutants', unit: file, cwd })
+  let text
+  let failed = null
+  try {
+    text = await callTextFn(prompt, { cwd, maxTokens: budgetFor('block').maxTokens, chain })
+  } catch (error) {
+    failed = String(error.message ?? error).slice(0, 200)
+    throw error
+  } finally {
+    chain.end({ outcome: failed ? 'fail' : 'success', extra: failed ? { error: failed } : {} })
+  }
+
+  let proposals
+  try {
+    proposals = JSON.parse(JSON_ARRAY_RE.exec(text)?.[0] ?? '[]')
+  } catch {
+    return []
+  }
+  if (!Array.isArray(proposals)) return []
+
+  const mutants = []
+  for (const p of proposals.slice(0, MAX_PROPOSALS)) {
+    const m = validateProposal(p, sourceLines, lineOffsets, coveredLines)
+    if (m && staysParseable(file, source, m)) mutants.push(m)
+  }
+  return mutants
+}

package/src/coverage/storybook-mutation.mjs

@@ -0,0 +1,361 @@
+/**
+ * Mutation testing для Storybook-покритого коду (vitest browser mode) — власний
+ * mutate→run→restore executor замість Stryker vitest-runner, який не підтримує
+ * сучасний Playwright-based browser mode (див. коментар над collectStorybookForRoot
+ * у js-collector.mjs).
+ *
+ * Патерн підтверджений дослідженням спільноти (alexop.dev, Mutahunter, Meta ACH):
+ * мутанти генеруються детерміновано, а вбиває/милує ЛИШЕ реальний прогін тестів —
+ * жодного LLM-суддівства pass/fail. Цикл на мутант: записати мутований файл →
+ * `vitest run --project=storybook [сторі-фільтр]` → KILLED (exit ≠ 0) / SURVIVED
+ * (exit 0) / TIMEOUT (kill за таймаутом, рахується як caught — мутант зламав
+ * поведінку до зависання) → відновити оригінал у `finally`.
+ *
+ * Генерація мутантів — AST-based (rollup `parseAst`, ESTree-shaped, вже у deps),
+ * без regex-хибняків у рядках/коментарях. Оператори — 5 тірів за ймовірністю
+ * виживання (catalog citypaul/alexop): boundary → logical → equality → literals/return
+ * → arithmetic. Мутуються лише рядки, покриті сторі (lcov `DA:`), з бюджетом
+ * (maxPerFile/maxTotal) — browser-mode прогін коштує секунди на мутант.
+ *
+ * `.vue` SFC: мутується лише вміст `<script>`/`<script setup>` блоку (template поза
+ * скоупом). `lang="ts"`-скрипти, які parseAst не бере, тихо пропускаються (0 мутантів).
+ */
+import { readFileSync, writeFileSync } from 'node:fs'
+import { isAbsolute, join, relative } from 'node:path'
+import { parseAst } from 'rollup/parseAst'
+
+/** Дефолтна стеля детермінованих мутантів на файл (тіри з нижчих номерів мають пріоритет). */
+const DEFAULT_MAX_PER_FILE = 8
+/** Дефолтна стеля додаткових (LLM-запропонованих) мутантів на файл — поверх детермінованої. */
+const DEFAULT_MAX_EXTRA_PER_FILE = 3
+/** Дефолтна стеля мутантів на весь прогін (спільна для обох джерел). */
+const DEFAULT_MAX_TOTAL = 32
+/** Мінімальний таймаут одного мутант-прогону (браузер холодний старт). */
+const MIN_TIMEOUT_MS = 30_000
+
+const SCRIPT_BLOCK_RE = /<script[^>]*>([\s\S]*?)<\/script>/
+const SCRIPT_LANG_TS_RE = /<script[^>]*\blang\s*=\s*["']ts["'][^>]*>/
+const VUE_FILE_RE = /\.vue$/
+
+/** Заміни операторів за тірами: tier 1 boundary, 2 logical, 3 equality, 5 arithmetic. */
+const BINARY_SWAPS = {
+  '<': { to: '<=', tier: 1, type: 'ConditionalExpression' },
+  '<=': { to: '<', tier: 1, type: 'ConditionalExpression' },
+  '>': { to: '>=', tier: 1, type: 'ConditionalExpression' },
+  '>=': { to: '>', tier: 1, type: 'ConditionalExpression' },
+  '===': { to: '!==', tier: 3, type: 'EqualityOperator' },
+  '!==': { to: '===', tier: 3, type: 'EqualityOperator' },
+  '==': { to: '!=', tier: 3, type: 'EqualityOperator' },
+  '!=': { to: '==', tier: 3, type: 'EqualityOperator' },
+  '-': { to: '+', tier: 5, type: 'ArithmeticOperator' },
+  '*': { to: '/', tier: 5, type: 'ArithmeticOperator' },
+  '/': { to: '*', tier: 5, type: 'ArithmeticOperator' }
+}
+const LOGICAL_SWAPS = {
+  '&&': { to: '||', tier: 2, type: 'LogicalOperator' },
+  '||': { to: '&&', tier: 2, type: 'LogicalOperator' }
+}
+
+/**
+ * Парс lcov.info у мапу «файл → покриті рядки» з `SF:`/`DA:<line>,<hits>` records.
+ * Шляхи рібейзяться відносно `baseDir` (lcov типово містить абсолютні шляхи).
+ * @param {string} text вміст lcov.info
+ * @param {string} baseDir корінь, відносно якого рібейзити шляхи (jsRoot)
+ * @returns {Map<string, Set<number>>} relative-шлях → множина покритих (hits > 0) рядків
+ */
+export function parseLcovCoveredLines(text, baseDir) {
+  const map = new Map()
+  let currentFile = null
+  let lines = null
+  for (const line of text.split('\n')) {
+    if (line.startsWith('SF:')) {
+      const raw = line.slice(3).trim()
+      currentFile = isAbsolute(raw) ? relative(baseDir, raw) : raw
+      lines = new Set()
+    } else if (line.startsWith('DA:') && lines) {
+      const comma = line.indexOf(',', 3)
+      const hits = Number(line.slice(comma + 1))
+      if (hits > 0) lines.add(Number(line.slice(3, comma)))
+    } else if (line === 'end_of_record' && currentFile) {
+      if (lines.size > 0 && !currentFile.startsWith('..')) map.set(currentFile, lines)
+      currentFile = null
+      lines = null
+    }
+  }
+  return map
+}
+
+/**
+ * Витягує JS-вміст для мутації: для `.vue` — перший `<script>`-блок (без TS),
+ * для решти — увесь файл. Експортовано для LLM-джерела мутантів
+ * (storybook-mutation-llm.mjs) — той самий скоуп і синтакс-валідація.
+ * @param {string} file відносний шлях файлу
+ * @param {string} source повний вміст файлу
+ * @returns {{code: string, offset: number} | null} код і зсув початку в повному файлі, або null (TS-скрипт / нема script-блоку)
+ */
+export function extractMutableCode(file, source) {
+  if (!VUE_FILE_RE.test(file)) return { code: source, offset: 0 }
+  if (SCRIPT_LANG_TS_RE.test(source)) return null
+  const m = SCRIPT_BLOCK_RE.exec(source)
+  if (!m) return null
+  return { code: m[1], offset: m.index + m[0].indexOf(m[1]) }
+}
+
+/**
+ * Індекс початків рядків для перекладу offset → {line, col} (line 1-indexed, col 0-indexed).
+ * @param {string} source повний вміст файлу
+ * @returns {number[]} зростаючі offsets початку кожного рядка
+ */
+function buildLineIndex(source) {
+  const starts = [0]
+  for (let i = 0; i < source.length; i++) {
+    if (source[i] === '\n') starts.push(i + 1)
+  }
+  return starts
+}
+
+/**
+ * Переводить абсолютний offset у позицію {line, col}.
+ * @param {number[]} lineStarts індекс із buildLineIndex
+ * @param {number} offset абсолютний offset у файлі
+ * @returns {{line: number, col: number}} line 1-indexed, col 0-indexed
+ */
+function offsetToPosition(lineStarts, offset) {
+  let lo = 0
+  let hi = lineStarts.length - 1
+  while (lo < hi) {
+    const mid = Math.ceil((lo + hi) / 2)
+    if (lineStarts[mid] <= offset) lo = mid
+    else hi = mid - 1
+  }
+  return { line: lo + 1, col: offset - lineStarts[lo] }
+}
+
+/**
+ * Рекурсивний обхід ESTree-вузлів.
+ * @param {object} node AST-вузол
+ * @param {(node: object) => void} visit колбек для кожного вузла з type
+ * @returns {void}
+ */
+function walkAst(node, visit) {
+  if (!node || typeof node !== 'object') return
+  if (Array.isArray(node)) {
+    for (const child of node) walkAst(child, visit)
+    return
+  }
+  if (typeof node.type === 'string') visit(node)
+  for (const key of Object.keys(node)) {
+    if (key === 'type' || key === 'start' || key === 'end') continue
+    walkAst(node[key], visit)
+  }
+}
+
+/**
+ * Мутація оператора binary/logical-виразу: знаходить текст оператора між
+ * `left.end` і `right.start` і формує splice-заміну.
+ * @param {object} node BinaryExpression/LogicalExpression вузол
+ * @param {string} code повний вміст файлу
+ * @param {{to: string, tier: number, type: string}} swap правило заміни
+ * @returns {{start: number, end: number, text: string, tier: number, mutantType: string} | null} splice або null, якщо оператор не знайдено текстуально
+ */
+function operatorMutation(node, code, swap) {
+  const between = code.slice(node.left.end, node.right.start)
+  const at = between.indexOf(node.operator)
+  if (at === -1) return null
+  const start = node.left.end + at
+  return { start, end: start + node.operator.length, text: swap.to, tier: swap.tier, mutantType: swap.type }
+}
+
+/**
+ * Генерує детерміновані мутанти для одного файлу (AST-based, лише покриті рядки).
+ * Тіри (пріоритет відбору): 1 boundary (`<`↔`<=`…), 2 logical (`&&`↔`||`, зняття `!`),
+ * 3 equality (`===`↔`!==`…), 4 literals/return (`true`↔`false`, `return X`→`return null`),
+ * 5 arithmetic (`-`↔`+`, `*`↔`/`). `+` свідомо не мутується (string-concat дає шумні
+ * псевдо-еквівалентні мутанти).
+ * @param {string} file відносний шлях (для .vue-детекції)
+ * @param {string} source повний вміст файлу
+ * @param {Set<number>} coveredLines покриті сторі рядки (1-indexed, з lcov DA)
+ * @returns {Array<{line: number, col: number, mutantType: string, original: string, replacement: string, start: number, end: number, text: string, tier: number}>} мутанти, відсортовані за (tier, line)
+ */
+export function generateMutants(file, source, coveredLines) {
+  const extracted = extractMutableCode(file, source)
+  if (!extracted) return []
+
+  let ast
+  try {
+    ast = parseAst(extracted.code)
+  } catch {
+    return [] // синтаксис поза parseAst (TS у .js тощо) — тихо без мутантів
+  }
+
+  const lineStarts = buildLineIndex(source)
+  const splices = []
+
+  walkAst(ast, node => {
+    if (node.type === 'BinaryExpression' && BINARY_SWAPS[node.operator]) {
+      const m = operatorMutation(node, extracted.code, BINARY_SWAPS[node.operator])
+      if (m) splices.push(m)
+    } else if (node.type === 'LogicalExpression' && LOGICAL_SWAPS[node.operator]) {
+      const m = operatorMutation(node, extracted.code, LOGICAL_SWAPS[node.operator])
+      if (m) splices.push(m)
+    } else if (node.type === 'UnaryExpression' && node.operator === '!' && node.prefix) {
+      splices.push({ start: node.start, end: node.argument.start, text: '', tier: 2, mutantType: 'BooleanNegation' })
+    } else if (node.type === 'Literal' && (node.value === true || node.value === false)) {
+      splices.push({
+        start: node.start,
+        end: node.end,
+        text: String(!node.value),
+        tier: 4,
+        mutantType: 'BooleanLiteral'
+      })
+    } else if (node.type === 'ReturnStatement' && node.argument && node.argument.raw !== 'null') {
+      splices.push({
+        start: node.argument.start,
+        end: node.argument.end,
+        text: 'null',
+        tier: 4,
+        mutantType: 'ReturnValue'
+      })
+    }
+  })
+
+  const mutants = []
+  for (const s of splices) {
+    const absStart = extracted.offset + s.start
+    const absEnd = extracted.offset + s.end
+    const pos = offsetToPosition(lineStarts, absStart)
+    if (!coveredLines.has(pos.line)) continue
+    mutants.push({
+      line: pos.line,
+      col: pos.col,
+      mutantType: s.mutantType,
+      original: source.slice(absStart, absEnd),
+      replacement: s.text,
+      start: absStart,
+      end: absEnd,
+      text: s.text,
+      tier: s.tier
+    })
+  }
+  return mutants.toSorted((a, b) => a.tier - b.tier || a.line - b.line || a.col - b.col)
+}
+
+/**
+ * Об'єднує детерміновані мутанти з додатковими (LLM-запропонованими), відкидаючи
+ * лише ТОЧНІ дублі (той самий [start, end) і та сама заміна). Перетин діапазонів —
+ * не дубль: мутація `5` всередині `return x < 5` і заміна всього аргументу на `null`
+ * — різні мутанти, обидва цінні.
+ * @param {Array<{start: number, end: number, text: string}>} deterministic детерміновані мутанти (пріоритет)
+ * @param {Array<{start: number, end: number, text: string}>} extra додаткові мутанти
+ * @returns {Array<object>} deterministic + недубльовані extra
+ */
+function mergeMutants(deterministic, extra) {
+  const merged = [...deterministic]
+  for (const e of extra) {
+    const duplicate = deterministic.some(d => d.start === e.start && d.end === e.end && d.text === e.text)
+    if (!duplicate) merged.push(e)
+  }
+  return merged
+}
+
+/**
+ * Виконує mutate→run→restore цикл для набору файлів одного Storybook-root.
+ *
+ * Гарантія відновлення: оригінальний вміст тримається в пам'яті і записується назад
+ * у `finally` після КОЖНОГО мутанта — жоден наступний прогін не бачить попередню
+ * мутацію, а креш процесу лишає щонайбільше один мутований файл (відновлюється
+ * `git checkout`, файл завжди у git — ми мутуємо лише tracked production-код).
+ *
+ * Класифікація: exit 0 → survived; exit ≠ 0 → killed; null status (kill за
+ * таймаутом spawnSync) → timeout, рахується як caught (мутант завісив виконання).
+ *
+ * `proposeExtraMutants` (опційно) — друге джерело мутантів (LLM, Mutahunter/ACH-патерн):
+ * ПРОПОНУЄ додаткові bug-like мутанти, але вбиває/милує так само лише реальний прогін.
+ * Додаткові мутанти мають ВЛАСНУ стелю (`maxExtraPerFile`) поверх детермінованої і
+ * дедуплікуються проти детермінованих за діапазоном; помилки хука (нема API-ключа
+ * тощо) — відповідальність самого хука (тут не ловляться).
+ * @param {object} opts опції прогону
+ * @param {string} opts.jsRoot абсолютний шлях workspace-кореня
+ * @param {string[]} opts.files відносні (до jsRoot) шляхи production-файлів для мутації
+ * @param {Map<string, Set<number>>} opts.coveredLines файл → покриті рядки (parseLcovCoveredLines)
+ * @param {(args: {cwd: string, storyFilter: string|null, timeoutMs: number}) => number|null} opts.runMutantTest прогін тестів проти мутованого дерева; повертає exit code або null при таймауті
+ * @param {(file: string) => string|null} [opts.resolveStoryFilter] відносний шлях сторі-файлу компонента для звуження прогону (null = увесь storybook-проєкт)
+ * @param {(file: string, source: string, coveredLines: Set<number>) => Promise<Array<object>>} [opts.proposeExtraMutants] друге джерело мутантів у тому ж shape, що generateMutants
+ * @param {number} [opts.timeoutMs] таймаут одного мутант-прогону
+ * @param {number} [opts.maxPerFile] стеля детермінованих мутантів на файл
+ * @param {number} [opts.maxExtraPerFile] стеля додаткових (LLM) мутантів на файл
+ * @param {number} [opts.maxTotal] стеля мутантів на прогін (спільна для обох джерел)
+ * @returns {Promise<{caught: number, total: number, survived: Array<{file: string, mutants: Array<{line: number, col: number, mutantType: string, original: string, replacement: string}>, exampleTest: null, recommendationText: null}>}>} результат у shape parseStrykerReport
+ */
+export async function runStorybookMutation(opts) {
+  const {
+    jsRoot,
+    files,
+    coveredLines,
+    runMutantTest,
+    resolveStoryFilter = () => null,
+    proposeExtraMutants = null,
+    timeoutMs = MIN_TIMEOUT_MS,
+    maxPerFile = DEFAULT_MAX_PER_FILE,
+    maxExtraPerFile = DEFAULT_MAX_EXTRA_PER_FILE,
+    maxTotal = DEFAULT_MAX_TOTAL
+  } = opts
+
+  let caught = 0
+  let total = 0
+  let budget = maxTotal
+  const survived = []
+
+  for (const file of files) {
+    if (budget <= 0) break
+    const lines = coveredLines.get(file)
+    if (!lines || lines.size === 0) continue
+
+    const absPath = join(jsRoot, file)
+    let source
+    try {
+      source = readFileSync(absPath, 'utf8')
+    } catch {
+      continue
+    }
+
+    const deterministic = generateMutants(file, source, lines).slice(0, maxPerFile)
+    const proposed = proposeExtraMutants ? await proposeExtraMutants(file, source, lines) : []
+    const mutants = mergeMutants(deterministic, proposed.slice(0, maxExtraPerFile)).slice(0, budget)
+    if (mutants.length === 0) continue
+    budget -= mutants.length
+
+    const storyFilter = resolveStoryFilter(file)
+    const survivedInFile = []
+
+    for (const mutant of mutants) {
+      const mutated = source.slice(0, mutant.start) + mutant.text + source.slice(mutant.end)
+      let status
+      try {
+        writeFileSync(absPath, mutated, 'utf8')
+        status = runMutantTest({ cwd: jsRoot, storyFilter, timeoutMs })
+      } finally {
+        writeFileSync(absPath, source, 'utf8')
+      }
+
+      total += 1
+      if (status === 0) {
+        survivedInFile.push({
+          line: mutant.line,
+          col: mutant.col,
+          mutantType: mutant.mutantType,
+          original: mutant.original,
+          replacement: mutant.replacement
+        })
+      } else {
+        caught += 1 // non-zero exit АБО timeout (null) — мутант впійманий
+      }
+    }
+
+    if (survivedInFile.length > 0) {
+      survived.push({ file, mutants: survivedInFile, exampleTest: null, recommendationText: null })
+    }
+  }
+
+  return { caught, total, survived }
+}

package/src/coverage/storybook.mjs

@@ -0,0 +1,75 @@
+/**
+ * Детекція Storybook-workspace-ів (Vue/React/... компоненти зі сторі), покриття
+ * яких рахує vitest browser mode через `@storybook/addon-vitest` (сучасна заміна
+ * legacy `@storybook/test-runner` + `@storybook/addon-coverage`). Root вважається
+ * Storybook-workspace лише коли є **обидва** сигнали — тека `.storybook/` (конфіг)
+ * і сам `@storybook/addon-vitest` у deps: самої теки замало (legacy Storybook без
+ * vitest-інтеграції теж має `.storybook/`), самого addon-у замало (може бути
+ * встановлений, але вимкнений/не налаштований).
+ */
+import { existsSync } from 'node:fs'
+import { readFile, readdir } from 'node:fs/promises'
+import { join } from 'node:path'
+
+/** `*.stories.*` файли — не production-код, окремий вимір покриття (Storybook, не JS-рядок). */
+export const STORIES_FILE_RE = /\.stories\.[^.]+$/
+
+const IGNORE_DIRS = new Set(['node_modules', 'dist', 'build', 'out', '.git', 'coverage', 'reports', 'docs', 'types'])
+
+/**
+ * Рекурсивний обхід каталогу з відсіюванням службових директорій (dot-теки, IGNORE_DIRS).
+ * @param {string} dir абсолютний шлях
+ * @param {(absPath: string) => void} onFile колбек для кожного файлу
+ * @returns {Promise<void>}
+ */
+async function walk(dir, onFile) {
+  let entries
+  try {
+    entries = await readdir(dir, { withFileTypes: true })
+  } catch {
+    return
+  }
+  for (const entry of entries) {
+    if (entry.name.startsWith('.')) continue
+    const abs = join(dir, entry.name)
+    if (entry.isDirectory()) {
+      if (!IGNORE_DIRS.has(entry.name)) await walk(abs, onFile)
+    } else if (entry.isFile()) {
+      onFile(abs)
+    }
+  }
+}
+
+/**
+ * Чи workspace налаштовано під Storybook coverage через vitest: тека `.storybook/`
+ * присутня **і** `@storybook/addon-vitest` декларовано в dependencies/devDependencies.
+ * @param {string} jsRoot абсолютний шлях workspace-кореня
+ * @returns {Promise<boolean>} true для Storybook-workspace з vitest-інтеграцією
+ */
+export async function isStorybookRoot(jsRoot) {
+  if (!existsSync(join(jsRoot, '.storybook'))) return false
+  const pkgPath = join(jsRoot, 'package.json')
+  if (!existsSync(pkgPath)) return false
+  let pkg
+  try {
+    pkg = JSON.parse(await readFile(pkgPath, 'utf8'))
+  } catch {
+    return false
+  }
+  return (
+    Boolean(pkg.dependencies?.['@storybook/addon-vitest']) || Boolean(pkg.devDependencies?.['@storybook/addon-vitest'])
+  )
+}
+
+/**
+ * Чи workspace має хоч один `*.stories.*` файл (`node_modules`/`dist`/… не скануються).
+ * @param {string} jsRoot абсолютний шлях workspace-кореня
+ * @returns {Promise<boolean>} true, якщо знайдено хоча б один сторі-файл
+ */
+export async function hasStories(jsRoot) {
+  let found = false
+  await walk(jsRoot, abs => {
+    if (STORIES_FILE_RE.test(abs)) found = true
+  })
+  return found
+}

package/src/coverage-per-file.mjs

@@ -12,7 +12,7 @@ import { join, relative } from 'node:path'
 import { env } from 'node:process'
 import { resolveVitestRun } from './lib/vitest-shim.mjs'
 
-const TEST_FILE_RE = /\.(test|spec)\.[^.]+$|(?:^|[/\\])tests?[/\\]/
+const TEST_FILE_RE = /\.(test|spec)\.[^.]+$|(?:^|[/\\])tests?[/\\]|\.stories\.[^.]+$/
 const VITEST_UNSUPPORTED_TEST_RE = /bun:test|Cannot find package 'bun/i
 const MAX_ERRORS_PER_FILE = 5
 const MAX_ERROR_LINES = 10

package/src/docs/coverage-fix.md

@@ -3,7 +3,7 @@ type: JS Module
 title: coverage-fix.mjs
 resource: npm/src/coverage-fix.mjs
 docgen:
-  crc: db577cf1
+  crc: eefeb364
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
 ---
 

package/src/docs/coverage-per-file.md

@@ -3,7 +3,7 @@ type: JS Module
 title: coverage-per-file.mjs
 resource: npm/src/coverage-per-file.mjs
 docgen:
-  crc: 388282cc
+  crc: 133b47a7
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 100
   issues: judge:inaccurate:0.98