@nitra/cursor 5.3.0 → 5.3.1

package/rules/npm-module/js/rule_meta.mjs

@@ -6,6 +6,77 @@ import { createCheckReporter } from '../../../scripts/lib/check-reporter.mjs'
 import { parseRuleAutoSpec, parseRuleLintPhase, readRuleMetaRaw } from '../../../scripts/lib/rule-meta.mjs'
 import { RULE_PREDICATES } from '../../../scripts/lib/rule-predicates.mjs'
 
+/**
+ * Перевіряє поле `auto` у meta.json одного правила.
+ * @param {string} id ідентифікатор правила
+ * @param {Record<string, unknown>} raw сирий meta.json
+ * @param {ReturnType<typeof createCheckReporter>} reporter репортер
+ * @returns {boolean} true, якщо поле валідне (або відсутнє)
+ */
+function checkAutoField(id, raw, reporter) {
+  if (raw.auto === undefined) return true
+  const spec = parseRuleAutoSpec(raw.auto)
+  if (spec === null) {
+    reporter.fail(`rules/${id}: meta.json.auto нерозпізнане (очікується "завжди" / масив / {glob} / {predicate})`)
+    return false
+  }
+  if ('predicate' in spec && !Object.hasOwn(RULE_PREDICATES, spec.predicate)) {
+    reporter.fail(`rules/${id}: невідомий predicate "${spec.predicate}" (немає в RULE_PREDICATES)`)
+    return false
+  }
+  return true
+}
+
+/**
+ * Перевіряє поле `lint` у meta.json одного правила.
+ * @param {string} id ідентифікатор правила
+ * @param {string} ruleDir каталог правила
+ * @param {Record<string, unknown>} raw сирий meta.json
+ * @param {ReturnType<typeof createCheckReporter>} reporter репортер
+ * @returns {boolean} true, якщо поле валідне (або відсутнє)
+ */
+function checkLintField(id, ruleDir, raw, reporter) {
+  if (raw.lint === undefined) return true
+  if (parseRuleLintPhase(raw.lint) === null) {
+    reporter.fail(`rules/${id}: meta.json.lint нерозпізнане (очікується "quick"|"ci")`)
+    return false
+  }
+  if (!existsSync(join(ruleDir, 'js', 'lint.mjs'))) {
+    reporter.fail(`rules/${id}: lint:"${raw.lint}" але немає js/lint.mjs`)
+    return false
+  }
+  return true
+}
+
+/**
+ * Валідує meta.json одного правила.
+ * @param {string} id ідентифікатор правила
+ * @param {string} ruleDir каталог правила
+ * @param {ReturnType<typeof createCheckReporter>} reporter репортер
+ * @returns {void}
+ */
+function checkRule(id, ruleDir, reporter) {
+  let ruleOk = true
+
+  if (existsSync(join(ruleDir, 'auto.md'))) {
+    reporter.fail(`rules/${id}: залишковий auto.md — видали (метадані тепер у meta.json)`)
+    ruleOk = false
+  }
+
+  const raw = readRuleMetaRaw(ruleDir)
+  if (!raw) {
+    reporter.fail(`rules/${id}: відсутній або невалідний meta.json`)
+    return
+  }
+
+  if (!checkAutoField(id, raw, reporter)) ruleOk = false
+  if (!checkLintField(id, ruleDir, raw, reporter)) ruleOk = false
+
+  if (ruleOk) {
+    reporter.pass(`rules/${id}: meta.json валідний`)
+  }
+}
+
 /**
  * Валідує всі `npm/rules/<id>/meta.json`.
  * @param {string} [cwd] корінь репозиторію
@@ -21,42 +92,7 @@ export function check(cwd = process.cwd()) {
 
   for (const entry of readdirSync(rulesDir, { withFileTypes: true })) {
     if (!entry.isDirectory() || entry.name.startsWith('.')) continue
-    const id = entry.name
-    const ruleDir = join(rulesDir, id)
-    let ruleOk = true
-
-    if (existsSync(join(ruleDir, 'auto.md'))) {
-      reporter.fail(`rules/${id}: залишковий auto.md — видали (метадані тепер у meta.json)`)
-      ruleOk = false
-    }
-
-    const raw = readRuleMetaRaw(ruleDir)
-    if (!raw) {
-      reporter.fail(`rules/${id}: відсутній або невалідний meta.json`)
-      continue
-    }
-    if (raw.auto !== undefined) {
-      const spec = parseRuleAutoSpec(raw.auto)
-      if (spec === null) {
-        reporter.fail(`rules/${id}: meta.json.auto нерозпізнане (очікується "завжди" / масив / {glob} / {predicate})`)
-        ruleOk = false
-      } else if ('predicate' in spec && !Object.hasOwn(RULE_PREDICATES, spec.predicate)) {
-        reporter.fail(`rules/${id}: невідомий predicate "${spec.predicate}" (немає в RULE_PREDICATES)`)
-        ruleOk = false
-      }
-    }
-    if (raw.lint !== undefined) {
-      if (parseRuleLintPhase(raw.lint) === null) {
-        reporter.fail(`rules/${id}: meta.json.lint нерозпізнане (очікується "quick"|"ci")`)
-        ruleOk = false
-      } else if (!existsSync(join(ruleDir, 'js', 'lint.mjs'))) {
-        reporter.fail(`rules/${id}: lint:"${raw.lint}" але немає js/lint.mjs`)
-        ruleOk = false
-      }
-    }
-    if (ruleOk) {
-      reporter.pass(`rules/${id}: meta.json валідний`)
-    }
+    checkRule(entry.name, join(rulesDir, entry.name), reporter)
   }
 
   return Promise.resolve(reporter.getExitCode())

package/rules/npm-module/js/skill_meta.mjs

@@ -5,6 +5,64 @@ import { join } from 'node:path'
 import { createCheckReporter } from '../../../scripts/lib/check-reporter.mjs'
 import { parseSkillAutoSpec, readSkillMetaRaw } from '../../../scripts/lib/skill-meta.mjs'
 
+/**
+ * Перевіряє поля сирого meta.json одного скіла (без auto.md / відсутності файлу).
+ * @param {string} id ідентифікатор скіла
+ * @param {Record<string, unknown>} raw сирий meta.json
+ * @param {ReturnType<typeof createCheckReporter>} reporter репортер
+ * @returns {boolean} true, якщо всі поля валідні
+ */
+function checkSkillFields(id, raw, reporter) {
+  let ok = true
+  if (typeof raw.worktree !== 'boolean') {
+    reporter.fail(`skills/${id}: meta.json.worktree має бути boolean`)
+    ok = false
+  }
+  if (raw.auto !== undefined && parseSkillAutoSpec(raw.auto) === null) {
+    reporter.fail(`skills/${id}: meta.json.auto нерозпізнане — очікується "завжди" або непорожній масив правил`)
+    ok = false
+  }
+  if (raw.requireRoot !== undefined && typeof raw.requireRoot !== 'boolean') {
+    reporter.fail(`skills/${id}: meta.json.requireRoot має бути boolean`)
+    ok = false
+  }
+  if (raw.worktree === true && raw.requireRoot === false) {
+    reporter.fail(
+      `skills/${id}: requireRoot:false суперечить worktree:true (worktree вже вимагає кореня — прибери поле)`
+    )
+    ok = false
+  }
+  return ok
+}
+
+/**
+ * Валідує meta.json одного скіла.
+ * @param {string} id ідентифікатор скіла
+ * @param {string} skillDir каталог скіла
+ * @param {ReturnType<typeof createCheckReporter>} reporter репортер
+ * @returns {void}
+ */
+function checkSkill(id, skillDir, reporter) {
+  let skillOk = true
+
+  if (existsSync(join(skillDir, 'auto.md'))) {
+    reporter.fail(`skills/${id}: залишковий auto.md — видали (метадані тепер у meta.json)`)
+    skillOk = false
+  }
+
+  const raw = readSkillMetaRaw(skillDir)
+  if (!raw) {
+    reporter.fail(`skills/${id}: відсутній або невалідний meta.json (очікується {"auto"?, "worktree": bool})`)
+    return
+  }
+
+  if (!checkSkillFields(id, raw, reporter)) skillOk = false
+
+  if (skillOk) {
+    reporter.pass(`skills/${id}: meta.json валідний`)
+  }
+}
+
 /**
  * Валідує всі `npm/skills/<id>/meta.json`.
  * @param {string} [cwd] корінь репозиторію
@@ -20,41 +78,7 @@ export function check(cwd = process.cwd()) {
 
   for (const entry of readdirSync(skillsDir, { withFileTypes: true })) {
     if (!entry.isDirectory() || entry.name.startsWith('.')) continue
-    const id = entry.name
-    const skillDir = join(skillsDir, id)
-    let skillOk = true
-
-    if (existsSync(join(skillDir, 'auto.md'))) {
-      reporter.fail(`skills/${id}: залишковий auto.md — видали (метадані тепер у meta.json)`)
-      skillOk = false
-    }
-
-    const raw = readSkillMetaRaw(skillDir)
-    if (!raw) {
-      reporter.fail(`skills/${id}: відсутній або невалідний meta.json (очікується {"auto"?, "worktree": bool})`)
-      continue
-    }
-    if (typeof raw.worktree !== 'boolean') {
-      reporter.fail(`skills/${id}: meta.json.worktree має бути boolean`)
-      skillOk = false
-    }
-    if (raw.auto !== undefined && parseSkillAutoSpec(raw.auto) === null) {
-      reporter.fail(`skills/${id}: meta.json.auto нерозпізнане — очікується "завжди" або непорожній масив правил`)
-      skillOk = false
-    }
-    if (raw.requireRoot !== undefined && typeof raw.requireRoot !== 'boolean') {
-      reporter.fail(`skills/${id}: meta.json.requireRoot має бути boolean`)
-      skillOk = false
-    }
-    if (raw.worktree === true && raw.requireRoot === false) {
-      reporter.fail(
-        `skills/${id}: requireRoot:false суперечить worktree:true (worktree вже вимагає кореня — прибери поле)`
-      )
-      skillOk = false
-    }
-    if (skillOk) {
-      reporter.pass(`skills/${id}: meta.json валідний`)
-    }
+    checkSkill(entry.name, join(skillsDir, entry.name), reporter)
   }
 
   return Promise.resolve(reporter.getExitCode())

package/scripts/coverage-classify/index.mjs

@@ -30,7 +30,7 @@ const FALLBACK_VERDICT = {
  * @param {string} prompt текст промпта
  * @param {string} model  provider/model-id, `omlx/...` або '' для pi-дефолту
  * @returns {string} текст відповіді моделі
- * @throws якщо backend недоступний або повертає помилку
+ * @throws {Error} якщо backend недоступний або повертає помилку
  */
 function callModel(prompt, model) {
   return callLlm([{ role: 'user', content: prompt }], model, { timeoutMs: 60_000, caller: 'coverage' })
@@ -68,7 +68,7 @@ function classifyOne(group, mutant, cwd, callModelFn) {
  * Класифікує survived мутантів (resolveModel('min') → CLOUD_MIN → fallback).
  * @param {Array<{file: string, mutants: object[], exampleTest?: object|null, recommendationText?: string|null}>} survived список вцілілих мутантів
  * @param {string} cwd корінь проєкту
- * @param {{cachePath?: string, callModel?: Function}} [opts] ін'єкції для тестів
+ * @param {{cachePath?: string, callModel?: (prompt: string, model: string) => string}} [opts] ін'єкції для тестів
  * @returns {Promise<Array<{key: string, verdict: object}>>} verdicts
  */
 export function classify(survived, cwd, opts = {}) {

package/scripts/coverage-classify/verdict-schema.mjs

@@ -22,7 +22,7 @@ export const VerdictSchema = z.object({
  * Витягує JSON-об'єкт з raw-text LLM-відповіді і валідує через VerdictSchema.
  * @param {string} rawText raw-text відповідь LLM
  * @returns {{verdict: string, confidence: number, reason: string, suggestedTest?: string}} verdict
- * @throws якщо JSON не знайдено, не парситься, або не відповідає схемі
+ * @throws {Error} якщо JSON не знайдено, не парситься, або не відповідає схемі
  */
 export function parseVerdict(rawText) {
   const jsonStart = rawText.indexOf('{')

package/scripts/lib/assert-project-root.mjs

@@ -1,5 +1,5 @@
 /**
- * Guard для дефолтної синхронізації `npx @nitra/cursor` (гілка без підкоманди).
+ * Guard для дефолтної синхронізації `npx \@nitra/cursor` (гілка без підкоманди).
  *
  * Дефолтний sync (`runSync` у `bin/n-cursor.js`) скаффолдить у `cwd()` керовані
  * артефакти — `.cursor/rules/`, `.cursor/skills/`, `.claude/`, `AGENTS.md`,

package/scripts/lib/discover-check-rules-from-cursor.mjs

@@ -1,5 +1,5 @@
 /**
- * Визначає список id правил для `npx @nitra/cursor fix` без аргументів:
+ * Визначає список id правил для `npx \@nitra/cursor fix` без аргументів:
  * зчитує базові імена `*.mdc` у `.cursor/rules/` і залишає лише ті id,
  * для яких у пакеті є programmatic перевірка (JS-концерн або policy з target.json).
  */

package/scripts/lib/rule-predicates.mjs

@@ -23,35 +23,44 @@ const IGNORED_DIR_NAMES = new Set(['node_modules', '.git', '.next', '.turbo'])
  */
 async function anyDepInTree(root, keys) {
   const wanted = new Set(keys)
-  let found = false
-  /** @param {string} dir каталог обходу @returns {Promise<void>} */
+  /**
+   * Чи package.json за `abs` оголошує будь-який пакет із `wanted` у `dependencies`.
+   * @param {string} abs шлях до package.json
+   * @returns {Promise<boolean>} true, якщо знайдено хоч один
+   */
+  async function pkgDeclaresWanted(abs) {
+    try {
+      const deps = JSON.parse(await readFile(abs, 'utf8'))?.dependencies
+      if (deps && typeof deps === 'object' && !Array.isArray(deps)) {
+        for (const k of wanted) if (Object.hasOwn(deps, k)) return true
+      }
+    } catch {
+      /* ігноруємо пошкоджені package.json */
+    }
+    return false
+  }
+  /**
+   * @param {string} dir каталог обходу
+   * @returns {Promise<boolean>} true, якщо знайдено хоч один пакет
+   */
   async function walk(dir) {
-    if (found) return
     let entries
     try {
       entries = await readdir(dir, { withFileTypes: true })
     } catch {
-      return
+      return false
     }
     for (const entry of entries) {
-      if (found) return
       const abs = join(dir, entry.name)
       if (entry.isDirectory()) {
-        if (!IGNORED_DIR_NAMES.has(entry.name)) await walk(abs)
-      } else if (entry.isFile() && entry.name === 'package.json') {
-        try {
-          const deps = JSON.parse(await readFile(abs, 'utf8'))?.dependencies
-          if (deps && typeof deps === 'object' && !Array.isArray(deps)) {
-            for (const k of wanted) if (Object.hasOwn(deps, k)) found = true
-          }
-        } catch {
-          /* ігноруємо пошкоджені package.json */
-        }
+        if (!IGNORED_DIR_NAMES.has(entry.name) && (await walk(abs))) return true
+      } else if (entry.isFile() && entry.name === 'package.json' && (await pkgDeclaresWanted(abs))) {
+        return true
       }
     }
+    return false
   }
-  await walk(root)
-  return found
+  return walk(root)
 }
 
 /**
@@ -62,7 +71,10 @@ async function anyDepInTree(root, keys) {
 async function nestedWithoutVite(root) {
   const rootPkg = join(root, 'package.json')
   let result = false
-  /** @param {string} dir каталог @returns {Promise<void>} */
+  /**
+   * @param {string} dir каталог
+   * @returns {Promise<void>}
+   */
   async function walk(dir) {
     if (result) return
     let entries

package/scripts/lib/run-rule-cli.mjs

@@ -1,7 +1,7 @@
 /**
  * Standalone CLI runner для одного правила. Викликається з `rules/<id>/fix.mjs`
  * у блоці `if (import.meta.main)` — це робить `bun rules/<id>/fix.mjs` повним
- * еквівалентом старого `npx @nitra/cursor fix <id>`: читає `.n-cursor.json`,
+ * еквівалентом старого `npx \@nitra/cursor fix <id>`: читає `.n-cursor.json`,
  * перевіряє whitelist, друкує summary, повертає aggregated exit-code.
  *
  * Library-mode виклик з CLI orchestration — інше: див. `runStandardRule` + `fix.mjs::run(ctx)`.

package/scripts/lib/run-standard-rule.mjs

@@ -5,7 +5,7 @@
  * Локальна логіка в правилах заборонена; розширення поведінки — через `ctx`-опції.
  *
  * Серіалізація: загортає виконання у `withLock('fix-<ruleId>')` — паралельні запуски
- * того самого правила (через `npx @nitra/cursor fix`, прямий `bun rules/<id>/fix.mjs`
+ * того самого правила (через `npx \@nitra/cursor fix`, прямий `bun rules/<id>/fix.mjs`
  * чи `run(ctx)`-композицію) дедупляться за станом git-дерева; різні правила можуть
  * виконуватись паралельно. Точка інтеграції — тут, щоб не дублювати лок у кожному
  * `fix.mjs`.

package/scripts/post-tool-use-fix.mjs

@@ -1,5 +1,5 @@
 /**
- * PostToolUse hook для Claude Code: точкова маршрутизація `npx @nitra/cursor fix`
+ * PostToolUse hook для Claude Code: точкова маршрутизація `npx \@nitra/cursor fix`
  * за типом зміненого файла. Запускається після кожного `Edit` / `Write` / `MultiEdit`;
  * замінює дорогий синхронний `Stop`-хук, що ганяв повний `fix` усіх правил на кожному
  * turn-і.
@@ -8,7 +8,7 @@
  * - stdin Claude Code: JSON із `tool_input.file_path` (відносний шлях зміненого файла);
  * - exit 0, якщо файл не має маршрут (PostToolUse не блокує turn у будь-якому випадку,
  *   але ми лишаємо exit-код прозорим — для діагностики);
- * - інакше spawn `npx --no @nitra/cursor fix <rules…>` із передаванням exit-коду.
+ * - інакше spawn `npx --no \@nitra/cursor fix <rules…>` із передаванням exit-коду.
  *
  * Маршрути впорядковані від найбільш специфічного до загального; перший збіг — переможець.
  * `docs/adr/**\/*.md` свідомо повертає `[]`: ADR-нормалізація вже покривається async
@@ -46,7 +46,7 @@ const ROUTES = Object.freeze([
  * Повертає список правил, які слід прогнати для зміненого `filePath`.
  * Перший збіг із `ROUTES` — переможець; невідомі шляхи / некоректні входи → `[]`.
  * @param {unknown} filePath відносний шлях зміненого файла зі stdin Claude Code
- * @returns {string[]} ID правил для `npx @nitra/cursor fix`
+ * @returns {string[]} ID правил для `npx \@nitra/cursor fix`
  */
 export function routeFilePathToRules(filePath) {
   if (typeof filePath !== 'string' || filePath === '') {

package/scripts/skills-cli.mjs

@@ -6,11 +6,11 @@
  * `.n-cursor.json`) — далі stdout або делегування в `cursor-agent` / `claude`.
  *
  * Підтримувані формати:
- *   `npx @nitra/cursor skill list`
- *   `npx @nitra/cursor skill taze`
- *   `npx @nitra/cursor skill cursor taze`
- *   `npx @nitra/cursor skill cursor taze "онови залежності"`
- *   `npx @nitra/cursor skill claude taze` — те саме через Claude Code CLI
+ *   `npx \@nitra/cursor skill list`
+ *   `npx \@nitra/cursor skill taze`
+ *   `npx \@nitra/cursor skill cursor taze`
+ *   `npx \@nitra/cursor skill cursor taze "онови залежності"`
+ *   `npx \@nitra/cursor skill claude taze` — те саме через Claude Code CLI
  */
 
 import { spawnSync } from 'node:child_process'

package/scripts/worktree-cli.mjs

@@ -79,7 +79,7 @@ function listDescFiles(cwd) {
 /**
  * add: створити worktree від HEAD + .md-опис.
  * @param {string[]} rest [branch, ...descParts]
- * @param {{ cwd: string, log: Function, logError: Function, now: () => Date }} ctx контекст
+ * @param {{ cwd: string, log: (line: string) => void, logError: (line: string) => void, now: () => Date }} ctx контекст
  * @returns {number} exit code
  */
 function cmdAdd(rest, ctx) {
@@ -135,7 +135,7 @@ function cmdAdd(rest, ctx) {
 /**
  * remove: прибрати checkout + .md (гілку лишає).
  * @param {string[]} rest [branch, ...flags]
- * @param {{ cwd: string, log: Function, logError: Function }} ctx контекст
+ * @param {{ cwd: string, log: (line: string) => void, logError: (line: string) => void }} ctx контекст
  * @returns {number} exit code
  */
 function cmdRemove(rest, ctx) {
@@ -167,7 +167,7 @@ function cmdRemove(rest, ctx) {
 
 /**
  * list: git worktree list + вміст .md-описів.
- * @param {{ cwd: string, log: Function }} ctx контекст
+ * @param {{ cwd: string, log: (line: string) => void }} ctx контекст
  * @returns {number} exit code
  */
 function cmdList(ctx) {
@@ -181,7 +181,7 @@ function cmdList(ctx) {
 
 /**
  * prune: git worktree prune + видалити осиротілі .md.
- * @param {{ cwd: string, log: Function }} ctx контекст
+ * @param {{ cwd: string, log: (line: string) => void }} ctx контекст
  * @returns {number} exit code
  */
 function cmdPrune(ctx) {
@@ -198,7 +198,7 @@ function cmdPrune(ctx) {
 /**
  * Точка входу підкоманди worktree.
  * @param {string[]} argv аргументи після `worktree`
- * @param {{ cwd?: string, log?: Function, logError?: Function, now?: () => Date }} [options] ін'єкція для тестів
+ * @param {{ cwd?: string, log?: (line: string) => void, logError?: (line: string) => void, now?: () => Date }} [options] ін'єкція для тестів
  * @returns {Promise<number>} exit code
  */
 export function runWorktreeCli(argv, options = {}) {

package/skills/doc-files/js/docgen-extract.mjs

@@ -65,7 +65,7 @@ function cleanJsDoc(raw) {
 }
 
 /**
- * Опис (без @-тегів) + параметри з @param як «name — опис».
+ * Опис (без @-тегів) + параметри з `@param` як «name — опис».
  * @param {string} raw сирий JSDoc-блок
  * @returns {{desc:string, params:Array<{name:string, desc:string}>, ret:string}} розпарсений опис, параметри й опис повернення
  */

package/skills/doc-files/js/docgen-files-batch.mjs

@@ -79,6 +79,68 @@ function preflightProblem() {
   return `omlx помилка: ${hc.detail}`
 }
 
+/**
+ * Текст-суфікс режиму для прогрес-рядка.
+ * @param {{ overwrite: boolean, retryDegraded: boolean }} mode режими
+ * @returns {string} ` (--overwrite)` / ` (--retry-degraded)` / порожній рядок
+ */
+function modeSuffix({ overwrite, retryDegraded }) {
+  if (overwrite) return ' (--overwrite)'
+  if (retryDegraded) return ' (--retry-degraded)'
+  return ''
+}
+
+/**
+ * Генерує й штампує доку для одного файлу, оновлюючи лічильники й прогрес.
+ * @param {object} file елемент scanForDocFiles
+ * @param {string} root абсолютний корінь
+ * @param {{ done: number, total: number }} progress позиція у прогресі
+ * @param {{ ok: number, degraded: number, err: number, errors: string[] }} stats акумулятор статистики
+ * @returns {Promise<void>}
+ */
+async function generateOne(file, root, progress, stats) {
+  const sourceAbs = join(root, file.sourcePath)
+  process.stdout.write(`  [${progress.done}/${progress.total}] ${file.sourcePath} … `)
+  try {
+    const docAbs = join(root, file.docPath)
+    // Варіант B: передаємо наявну доку, щоб зберегти захищену секцію «Призначення»
+    const existingMd = existsSync(docAbs) ? readFileSync(docAbs, 'utf8') : null
+    const result = await generateDoc(sourceAbs, { existingMd })
+    const crc = crc32(readFileSync(sourceAbs))
+    mkdirSync(dirname(docAbs), { recursive: true })
+    const quality =
+      result.score === null ? null : { score: result.score, issues: result.degraded ? result.issues : [] }
+    writeFileSync(docAbs, stampDoc(result.md, file.sourcePath, crc, quality))
+    stats.ok++
+    if (result.degraded) {
+      stats.degraded++
+      process.stdout.write(`⚠ degraded score=${result.score} crc=${crc}\n`)
+    } else {
+      process.stdout.write(`✓ score=${result.score ?? '—'} crc=${crc}\n`)
+    }
+  } catch (error) {
+    stats.err++
+    stats.errors.push(file.sourcePath)
+    process.stdout.write(`✗ ${error.message}\n`)
+  }
+}
+
+/**
+ * Підсумковий звіт прогону у stdout.
+ * @param {{ ok: number, degraded: number, err: number, errors: string[] }} stats статистика
+ * @returns {void}
+ */
+function reportStats(stats) {
+  console.log(`\n${'─'.repeat(50)}\n✓ OK: ${stats.ok}  ⚠ degraded: ${stats.degraded}  ✗ Err: ${stats.err}`)
+  if (stats.errors.length > 0) {
+    console.log('Помилки:')
+    for (const e of stats.errors) console.log(`  - ${e}`)
+  }
+  if (stats.degraded > 0) {
+    console.log(`Degraded-доки перегенеровуються пізніше: npx @nitra/cursor doc-files gen --retry-degraded`)
+  }
+}
+
 /**
  * `doc-files gen` — згенерувати документацію для застарілих/відсутніх док.
  * @param {string[]} argv аргументи після назви субкоманди
@@ -106,47 +168,16 @@ export async function runDocFilesGenCli(argv) {
     return 1
   }
 
-  let modeTxt = ''
-  if (overwrite) modeTxt = ' (--overwrite)'
-  else if (retryDegraded) modeTxt = ' (--retry-degraded)'
-  console.log(`📋 doc-files: до генерації ${targets.length} файл(ів)${modeTxt}`)
+  console.log(`📋 doc-files: до генерації ${targets.length} файл(ів)${modeSuffix({ overwrite, retryDegraded })}`)
   const stats = { ok: 0, degraded: 0, err: 0, errors: [] }
 
   let done = 0
   for (const file of targets) {
     done++
-    const sourceAbs = join(root, file.sourcePath)
-    process.stdout.write(`  [${done}/${targets.length}] ${file.sourcePath} … `)
-    try {
-      const result = await generateDoc(sourceAbs)
-      const crc = crc32(readFileSync(sourceAbs))
-      const docAbs = join(root, file.docPath)
-      mkdirSync(dirname(docAbs), { recursive: true })
-      const quality =
-        result.score === null ? null : { score: result.score, issues: result.degraded ? result.issues : [] }
-      writeFileSync(docAbs, stampDoc(result.md, file.sourcePath, crc, quality))
-      stats.ok++
-      if (result.degraded) {
-        stats.degraded++
-        process.stdout.write(`⚠ degraded score=${result.score} crc=${crc}\n`)
-      } else {
-        process.stdout.write(`✓ score=${result.score ?? '—'} crc=${crc}\n`)
-      }
-    } catch (error) {
-      stats.err++
-      stats.errors.push(file.sourcePath)
-      process.stdout.write(`✗ ${error.message}\n`)
-    }
+    await generateOne(file, root, { done, total: targets.length }, stats)
   }
 
-  console.log(`\n${'─'.repeat(50)}\n✓ OK: ${stats.ok}  ⚠ degraded: ${stats.degraded}  ✗ Err: ${stats.err}`)
-  if (stats.errors.length > 0) {
-    console.log('Помилки:')
-    for (const e of stats.errors) console.log(`  - ${e}`)
-  }
-  if (stats.degraded > 0) {
-    console.log(`Degraded-доки перегенеровуються пізніше: npx @nitra/cursor doc-files gen --retry-degraded`)
-  }
+  reportStats(stats)
   return stats.err > 0 ? 1 : 0
 }