@7n/rules 1.0.0

package/scripts/lib/ensure-tool.mjs

@@ -0,0 +1,352 @@
+/**
+ * Авто-встановлення зовнішніх CLI-залежностей пакету `@7n/rules`.
+ *
+ * `ensureTool(toolId)` — єдиний seam резолву зовнішніх бінарників: PATH → кеш → авто-install → hard-fail.
+ * Новий тул = один запис у реєстрі `TOOLS`, без дублювання install-логіки в кожному `lint.mjs`/`fix.mjs`.
+ *
+ * Per-platform matrix: macOS → brew, Windows → scoop (fallback: GitHub Release), Linux → GitHub Release binary.
+ * Бінарники кешуються у `~/.cache/@7n/rules/bin/` (Linux/Mac), `%LOCALAPPDATA%\@7n\cursor\bin\` (Win).
+ *
+ * `ensureHkInstall(hkBin)` — реєструє git pre-commit hook через `hk install`; пропускається в CI.
+ */
+import { spawnSync } from 'node:child_process'
+import { chmodSync, existsSync, mkdirSync, renameSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import { arch, env, platform } from 'node:process'
+
+import { resolveCmd } from '../utils/resolve-cmd.mjs'
+
+/** Префікс `v` у git-тегу релізу (`v1.2.3` → `1.2.3`). */
+const TAG_V_PREFIX_RE = /^v/
+
+/**
+ * Повертає каталог керованого кешу бінарників для поточного OS.
+ * @returns {string} абсолютний шлях
+ */
+function getCacheDir() {
+  if (platform === 'win32') {
+    const localAppData = env['LOCALAPPDATA'] ?? join(homedir(), 'AppData', 'Local')
+    return join(localAppData, '@7n', 'rules', 'bin')
+  }
+  return join(homedir(), '.cache', '@7n', 'rules', 'bin')
+}
+
+/**
+ * Мапить `process.arch` у формат, що вживається в назвах GitHub-release ресурсів.
+ * @param {'x64'|'arm64'|string} nodeArch значення `process.arch`
+ * @param {'hk'|'conftest'|'actionlint'} style стиль іменування платформи
+ * @returns {string} рядок архітектури для asset-шаблону
+ */
+function mapArch(nodeArch, style) {
+  if (style === 'actionlint') {
+    return nodeArch === 'x64' ? 'amd64' : 'arm64'
+  }
+  if (style === 'conftest') {
+    return nodeArch === 'x64' ? 'x86_64' : 'arm64'
+  }
+  // hk / shellcheck / dotenv-linter: x64 → x86_64, arm64 → aarch64
+  return nodeArch === 'x64' ? 'x86_64' : 'aarch64'
+}
+
+/**
+ * @typedef {object} ToolEntry
+ * @property {string} brew формула brew (macOS)
+ * @property {string|null} scoop назва пакету scoop (Windows); null = недоступний
+ * @property {string} github репо у форматі `owner/repo`
+ * @property {(ver: string) => string} asset повертає назву release-ресурсу для Linux
+ * @property {string} archStyle стиль маппінгу архітектури: 'hk'|'conftest'|'actionlint'
+ * @property {boolean} [archive] чи є release-ресурс архівом (tar) — default `true`; `false` = сирий бінарник (download + chmod)
+ * @property {((ver: string) => string)|null} [binFinder] для архівів де бінарник не у корені; повертає відносний шлях
+ */
+
+/** @type {Record<string, ToolEntry>} */
+const TOOLS = {
+  hk: {
+    brew: 'hk',
+    scoop: 'hk',
+    github: 'jdx/hk',
+    archStyle: 'hk',
+    asset: _ver => `hk-${mapArch(arch, 'hk')}-unknown-linux-gnu.tar.gz`,
+    binFinder: null
+  },
+  conftest: {
+    brew: 'conftest',
+    scoop: 'conftest',
+    github: 'open-policy-agent/conftest',
+    archStyle: 'conftest',
+    asset: ver => `conftest_${ver}_Linux_${mapArch(arch, 'conftest')}.tar.gz`,
+    binFinder: null
+  },
+  shellcheck: {
+    brew: 'shellcheck',
+    scoop: 'shellcheck',
+    github: 'koalaman/shellcheck',
+    archStyle: 'hk',
+    asset: ver => `shellcheck-v${ver}.linux.${mapArch(arch, 'hk')}.tar.xz`,
+    binFinder: ver => `shellcheck-v${ver}/shellcheck`
+  },
+  actionlint: {
+    brew: 'actionlint',
+    scoop: 'actionlint',
+    github: 'rhysd/actionlint',
+    archStyle: 'actionlint',
+    asset: ver => `actionlint_${ver}_linux_${mapArch(arch, 'actionlint')}.tar.gz`,
+    binFinder: null
+  },
+  'dotenv-linter': {
+    brew: 'dotenv-linter',
+    scoop: null,
+    github: 'dotenv-linter/dotenv-linter',
+    archStyle: 'hk',
+    asset: _ver => `dotenv-linter-linux-${mapArch(arch, 'hk')}.tar.gz`,
+    binFinder: null
+  },
+  opa: {
+    brew: 'opa',
+    scoop: 'opa',
+    github: 'open-policy-agent/opa',
+    archStyle: 'actionlint',
+    archive: false,
+    asset: _ver => `opa_linux_${mapArch(arch, 'actionlint')}`,
+    binFinder: null
+  },
+  regal: {
+    brew: 'regal',
+    scoop: null,
+    github: 'StyraInc/regal',
+    archStyle: 'conftest',
+    archive: false,
+    asset: _ver => `regal_Linux_${mapArch(arch, 'conftest')}`,
+    binFinder: null
+  },
+  hadolint: {
+    brew: 'hadolint',
+    scoop: 'hadolint',
+    github: 'hadolint/hadolint',
+    archStyle: 'conftest',
+    archive: false,
+    asset: _ver => `hadolint-linux-${mapArch(arch, 'conftest')}`,
+    binFinder: null
+  },
+  kubeconform: {
+    brew: 'kubeconform',
+    scoop: 'kubeconform',
+    github: 'yannh/kubeconform',
+    archStyle: 'actionlint',
+    asset: _ver => `kubeconform-linux-${mapArch(arch, 'actionlint')}.tar.gz`,
+    binFinder: null
+  },
+  kubescape: {
+    brew: 'kubescape',
+    scoop: 'kubescape',
+    github: 'kubescape/kubescape',
+    archStyle: 'actionlint',
+    archive: false,
+    asset: ver => `kubescape_${ver}_linux_${mapArch(arch, 'actionlint')}`,
+    binFinder: null
+  }
+}
+
+/**
+ * Отримує останній тег з GitHub Releases API через curl (sync).
+ * @param {string} repo репо у форматі `owner/repo`
+ * @param {string} curlBin абсолютний шлях до curl
+ * @returns {string} рядок версії без префікса `v`, наприклад `0.4.1`
+ */
+function fetchLatestVersion(repo, curlBin) {
+  const url = `https://api.github.com/repos/${repo}/releases/latest`
+  const r = spawnSync(curlBin, ['-sSL', '-H', 'Accept: application/vnd.github+json', url], { encoding: 'utf8' })
+  if (r.error) throw new Error(`curl failed: ${r.error.message}`)
+  if (r.status !== 0) throw new Error(`curl exit ${r.status}: ${(r.stderr ?? '').slice(0, 300)}`)
+  let parsed
+  try {
+    parsed = JSON.parse(r.stdout)
+  } catch {
+    throw new Error(`GitHub API response is not JSON: ${r.stdout.slice(0, 200)}`)
+  }
+  const tag = parsed['tag_name']
+  if (!tag) throw new Error(`GitHub API: tag_name missing for ${repo}`)
+  return tag.replace(TAG_V_PREFIX_RE, '')
+}
+
+/**
+ * Завантажує та розпаковує GitHub Release бінарник у кеш-директорію.
+ * Повертає абсолютний шлях до бінарника.
+ * @param {string} toolId ключ у TOOLS
+ * @param {ToolEntry} entry опис тула
+ * @param {string} cacheDir абсолютний шлях до кешу
+ * @returns {string} абсолютний шлях до готового бінарника
+ */
+function installFromGithub(toolId, entry, cacheDir) {
+  const curlBin = resolveCmd('curl')
+  if (!curlBin) throw new Error(`curl не знайдено в PATH — потрібен для завантаження ${toolId}`)
+  const tarBin = resolveCmd('tar')
+  if (!tarBin) throw new Error(`tar не знайдено в PATH — потрібен для встановлення ${toolId}`)
+
+  const ver = fetchLatestVersion(entry.github, curlBin)
+  const assetName = entry.asset(ver)
+  const downloadUrl = `https://github.com/${entry.github}/releases/download/v${ver}/${assetName}`
+
+  mkdirSync(cacheDir, { recursive: true })
+  const archivePath = join(cacheDir, assetName)
+
+  const dlResult = spawnSync(curlBin, ['-sSL', '-o', archivePath, downloadUrl], { encoding: 'utf8' })
+  if (dlResult.error) throw new Error(`Завантаження ${toolId} не вдалось: ${dlResult.error.message}`)
+  if (dlResult.status !== 0)
+    throw new Error(`curl exit ${dlResult.status} при завантаженні ${toolId}: ${(dlResult.stderr ?? '').slice(0, 300)}`)
+
+  // Сирий бінарник (archive: false) — завантажений файл і є бінарником: перейменовуємо у <toolId> + chmod.
+  if (entry.archive === false) {
+    const binPath = join(cacheDir, toolId)
+    renameSync(archivePath, binPath)
+    chmodSync(binPath, 0o755)
+    return binPath
+  }
+
+  // .tar.xz потребує -J замість -z
+  const isXz = assetName.endsWith('.tar.xz')
+  const tarFlags = isXz ? ['-xJf'] : ['-xzf']
+  const extractResult = spawnSync(tarBin, [...tarFlags, archivePath, '-C', cacheDir], { encoding: 'utf8' })
+  if (extractResult.error) throw new Error(`tar failed for ${toolId}: ${extractResult.error.message}`)
+  if (extractResult.status !== 0)
+    throw new Error(`tar exit ${extractResult.status} для ${toolId}: ${(extractResult.stderr ?? '').slice(0, 300)}`)
+
+  const binRelPath = entry.binFinder ? entry.binFinder(ver) : toolId
+  const binPath = join(cacheDir, binRelPath)
+  if (!existsSync(binPath)) {
+    throw new Error(`Бінарник ${toolId} не знайдено після розпакування: ${binPath}`)
+  }
+
+  const rmBin = resolveCmd('rm')
+  if (rmBin) spawnSync(rmBin, [archivePath])
+
+  return binPath
+}
+
+/**
+ * Встановлює тул через brew (macOS). Hard-fail на будь-яку помилку.
+ * @param {string} toolId ключ у TOOLS
+ * @param {ToolEntry} entry опис тула
+ * @returns {string} абсолютний шлях до встановленого бінарника
+ */
+function installViaBrew(toolId, entry) {
+  const brewBin = resolveCmd('brew')
+  if (!brewBin) throw new Error(`brew не знайдено в PATH. Встанови Homebrew: https://brew.sh`)
+  const r = spawnSync(brewBin, ['install', entry.brew], { stdio: 'inherit', encoding: 'utf8' })
+  if (r.error) throw new Error(`brew install ${toolId} не вдалось: ${r.error.message}`)
+  if (r.status !== 0) throw new Error(`brew install ${toolId} завершився з кодом ${r.status}`)
+  const resolved = resolveCmd(toolId)
+  if (!resolved) throw new Error(`${toolId} не знайдено в PATH після brew install`)
+  return resolved
+}
+
+/**
+ * Встановлює тул через scoop (Windows). Кидає якщо scoop недоступний або пакет null.
+ * @param {string} toolId ключ у TOOLS
+ * @param {ToolEntry} entry опис тула
+ * @returns {string} абсолютний шлях до встановленого бінарника
+ */
+function installViaScoop(toolId, entry) {
+  if (!entry.scoop) {
+    throw new Error(`${toolId} недоступний у Scoop. Встанови вручну:\n   https://github.com/${entry.github}/releases`)
+  }
+  const scoopBin = resolveCmd('scoop')
+  if (!scoopBin) throw new Error(`scoop не знайдено в PATH. Встанови Scoop: https://scoop.sh`)
+  const r = spawnSync(scoopBin, ['install', entry.scoop], { stdio: 'inherit', encoding: 'utf8' })
+  if (r.error) throw new Error(`scoop install ${toolId} не вдалось: ${r.error.message}`)
+  if (r.status !== 0) throw new Error(`scoop install ${toolId} завершився з кодом ${r.status}`)
+  const resolved = resolveCmd(toolId)
+  if (!resolved) throw new Error(`${toolId} не знайдено в PATH після scoop install`)
+  return resolved
+}
+
+/**
+ * Виконує авто-встановлення тула відповідно до поточного OS.
+ * @param {string} toolId ключ у TOOLS
+ * @param {ToolEntry} entry опис тула
+ * @param {string} cacheDir каталог кешу для Linux-бінарників
+ * @returns {string} абсолютний шлях до бінарника
+ */
+function autoInstall(toolId, entry, cacheDir) {
+  if (platform === 'darwin') return installViaBrew(toolId, entry)
+  if (platform === 'win32') {
+    try {
+      return installViaScoop(toolId, entry)
+    } catch {
+      // Scoop недоступний або тул не в Scoop → GitHub Release fallback
+      return installFromGithub(toolId, entry, cacheDir)
+    }
+  }
+  // Linux
+  return installFromGithub(toolId, entry, cacheDir)
+}
+
+/**
+ * Будує install-hint повідомлення для hard-fail.
+ * @param {string} toolId ключ у TOOLS
+ * @param {ToolEntry} entry опис тула
+ * @returns {string} рядок помилки з підказками
+ */
+function buildHint(toolId, entry) {
+  const lines = [
+    `❌ ${toolId} не знайдено в PATH і авто-встановлення відключено (N_CURSOR_NO_AUTO_INSTALL).`,
+    '   Встанови:'
+  ]
+  if (platform === 'darwin') {
+    lines.push(`     macOS: brew install ${entry.brew}`)
+  } else if (platform === 'win32') {
+    if (entry.scoop) lines.push(`     Windows: scoop install ${entry.scoop}`)
+    lines.push(`     або: https://github.com/${entry.github}/releases`)
+  } else {
+    lines.push(`     Linux: https://github.com/${entry.github}/releases`)
+  }
+  return lines.join('\n')
+}
+
+/**
+ * Резолвить і за необхідності авто-встановлює зовнішній CLI-тул.
+ *
+ * Порядок: PATH → кеш → авто-install (якщо не N_CURSOR_NO_AUTO_INSTALL) → hard-fail.
+ * Повертає абсолютний шлях або кидає Error.
+ * @param {string} toolId ключ у реєстрі TOOLS (`'hk'`, `'conftest'`, `'shellcheck'`, `'actionlint'`, `'dotenv-linter'`, `'opa'`, `'regal'`, `'hadolint'`, `'kubeconform'`, `'kubescape'`)
+ * @returns {string} абсолютний шлях до бінарника
+ */
+export function ensureTool(toolId) {
+  const entry = TOOLS[toolId]
+  if (!entry) throw new Error(`ensureTool: невідомий тул '${toolId}'`)
+
+  // 1. PATH
+  const fromPath = resolveCmd(toolId)
+  if (fromPath) return fromPath
+
+  // 2. Кеш
+  const cacheDir = getCacheDir()
+  const cachedBin = join(cacheDir, toolId)
+  if (existsSync(cachedBin)) return cachedBin
+
+  // 3. Авто-install (якщо не заблоковано)
+  if (!env['N_CURSOR_NO_AUTO_INSTALL']) {
+    return autoInstall(toolId, entry, cacheDir)
+  }
+
+  // 4. Hard-fail з per-OS підказкою
+  throw new Error(buildHint(toolId, entry))
+}
+
+/**
+ * Реєструє git pre-commit hook через `hk install`.
+ * Пропускається в CI (`process.env.CI`). Попереджає (не кидає) на помилку.
+ * @param {string} hkBin абсолютний шлях до бінарника hk
+ * @returns {void}
+ */
+export function ensureHkInstall(hkBin) {
+  if (env['CI']) return
+
+  const r = spawnSync(hkBin, ['install'], { stdio: 'inherit', encoding: 'utf8' })
+  if (r.error) {
+    console.warn(`⚠️ hk install не вдалось: ${r.error.message}`)
+  } else if (r.status !== 0) {
+    console.warn(`⚠️ hk install завершився з кодом ${r.status}`)
+  }
+}

package/scripts/lib/fix/docs/index.md

@@ -0,0 +1,11 @@
+---
+type: Directory Index
+title: npm/scripts/lib/fix
+resource: npm/scripts/lib/fix/
+---
+
+# npm/scripts/lib/fix
+
+| Файл                                    | Тип       |
+| --------------------------------------- | --------- |
+| [vscode-ext-add.mjs](vscode-ext-add.md) | JS Module |

package/scripts/lib/fix/docs/vscode-ext-add.md

@@ -0,0 +1,33 @@
+---
+type: JS Module
+title: vscode-ext-add.mjs
+resource: npm/scripts/lib/fix/vscode-ext-add.mjs
+docgen:
+  crc: 8b3e27a9
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+  issues: judge:inaccurate:0.98
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+## Огляд
+
+Цей механізм автоматично ідентифікує та доповнює конфігураційні файли розширень VS Code, корегуючи їх відповідно до вимог, заданих у правилах `vscode_extensions.rego`. Публічна функція `patterns` виконує перехоплення помилок (fail-safe), не генеруючи винятків. Механізм є універсальним для будь-яких правил, що вимагають наявності певної назви розширення у списку рекомендацій, і працює з конфігом `extensions.json`. Він витягує назви розширень із повідомлення про порушення та додає їх у список `recommendations` у `.vscode/extensions.json` при його наявності, без використання кешування.
+
+## Поведінка
+
+1. Ініціалізується набір правил `patterns` для автоматичного виправлення помилок, пов'язаних з конфігурацією розширень VS Code.
+2. Кожне правило в `patterns` перевіряє, чи виявлено повідомлення про порушення, що містить вимогу щодо включення назви розширення.
+3. Якщо порушення виявлено, система шукає назви розширень у повідомленні про порушення.
+4. Перевіряється існування файлу `.vscode/extensions.json` у поточному каталозі.
+5. Зчитується вміст файлу `.vscode/extensions.json` і парситься як JSON.
+6. Якщо парсинг не вдається або файл відсутній, дія вважається невдалою.
+7. Визначається список вже присутніх рекомендацій у файлі.
+8. Формується список нових назв розширень, які необхідно додати, відфільтровуючи ті, що вже присутні.
+9. Якщо нові розширення є, їх додають до списку `recommendations` у файлі `.vscode/extensions.json`.
+10. Оновлений вміст файлу `.vscode/extensions.json` записується назад.
+11. Результат операції фіксується відповідним повідомленням.
+
+## Гарантії поведінки
+
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).

package/scripts/lib/fix/vscode-ext-add.mjs

@@ -0,0 +1,53 @@
+/**
+ * Shared T0-autofix паттерн для правил із `vscode_extensions` policy-поверхнею.
+ * Гарантує, що `.vscode/extensions.json#recommendations` містить усі канонічні
+ * розширення з `template/extensions.json.snippet.json` свого concern-а (створює файл
+ * якщо відсутній, домерджує відсутні). Один механізм для всіх vscode_extensions-правил.
+ *
+ * Unified lint surface: structured violations (test(violations)/apply(violations,ctx)),
+ * канон читається з template концерну (ctx.concernDir), не з тексту violation.
+ */
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs'
+import { join, dirname } from 'node:path'
+
+const REC_REQUIRE_RE = /recommendations має містити|extensions\.json/u
+
+/** @type {import('../lint-surface/types.mjs').T0Pattern[]} */
+export const patterns = [
+  {
+    id: 'vscode-ext-add',
+    test: violations => violations.some(v => v.reason === 'policy-file-missing' || REC_REQUIRE_RE.test(v.message)),
+    apply: (violations, ctx) => {
+      const snippetPath = ctx.concernDir ? join(ctx.concernDir, 'template', 'extensions.json.snippet.json') : null
+      if (!snippetPath || !existsSync(snippetPath)) return { touchedFiles: [] }
+
+      /** @type {string[]} */
+      let canonical
+      try {
+        canonical = JSON.parse(readFileSync(snippetPath, 'utf8')).recommendations ?? []
+      } catch {
+        return { touchedFiles: [] }
+      }
+      if (canonical.length === 0) return { touchedFiles: [] }
+
+      const extPath = join(ctx.cwd, '.vscode/extensions.json')
+      let parsed = {}
+      if (existsSync(extPath)) {
+        try {
+          parsed = JSON.parse(readFileSync(extPath, 'utf8'))
+        } catch {
+          return { touchedFiles: [] } // невалідний JSON — не чіпаємо детермінованим фіксом
+        }
+      }
+      const recs = Array.isArray(parsed.recommendations) ? parsed.recommendations : []
+      const toAdd = canonical.filter(e => !recs.includes(e))
+      if (toAdd.length === 0 && existsSync(extPath)) return { touchedFiles: [] }
+
+      ctx.recordWrite?.(extPath)
+      parsed.recommendations = [...recs, ...toAdd]
+      mkdirSync(dirname(extPath), { recursive: true })
+      writeFileSync(extPath, JSON.stringify(parsed, null, 2) + '\n', 'utf8')
+      return { touchedFiles: [extPath], message: `extensions.json: +${toAdd.join(', ') || 'created'}` }
+    }
+  }
+]

package/scripts/lib/generated-markdown.mjs

@@ -0,0 +1,71 @@
+/**
+ * Утиліти генерації AGENTS.md / CLAUDE.md з шаблонів CLI `n-rules`.
+ *
+ * Після розгортання Mustache-секцій і збирання рядків CLAUDE.md нормалізує markdown,
+ * щоб не лишати подвійні порожні рядки (MD012) між пунктами списку чи на стиках секцій.
+ */
+
+/**
+ * Згортає три й більше послідовних `\n` до рівно двох (один порожній рядок між блоками).
+ * @param {string} text вихідний markdown
+ * @returns {string} markdown без послідовностей з трьох і більше `\n`
+ */
+export function collapseMultipleBlankLines(text) {
+  return String(text).replaceAll(/\n{3,}/g, '\n\n')
+}
+
+/**
+ * Розгортає блок Mustache `{{#section}}…{{/section}}` для масиву елементів.
+ * Після `trim` тіла секції елементи зʼєднуються одним `\n` без зайвих порожніх рядків між ними.
+ * @param {string} template вихідний текст шаблону
+ * @param {string} section ім'я секції (наприклад services)
+ * @param {Record<string, string>[]} items елементи для повторення тіла секції
+ * @param {string} prop ключ поля для підстановки замість `{{prop}}`
+ * @returns {string} шаблон після підстановки всіх входжень блоку секції
+ */
+export function expandMustacheSection(template, section, items, prop) {
+  const open = `{{#${section}}}`
+  const close = `{{/${section}}}`
+  const placeholder = `{{${prop}}}`
+  let result = template
+  let start = result.indexOf(open)
+  let end = result.indexOf(close)
+  while (start !== -1 && end !== -1 && end > start) {
+    const inner = result.slice(start + open.length, end).trim()
+    const rendered = items.map(item => inner.split(placeholder).join(String(item[prop]))).join('\n')
+    result = result.slice(0, start) + rendered + result.slice(end + close.length)
+    start = result.indexOf(open)
+    end = result.indexOf(close)
+  }
+  return result
+}
+
+/**
+ * Підставляє у AGENTS.template.md списки правил, skills і команд.
+ * @param {string} templateText вміст AGENTS.template.md
+ * @param {string[]} mdcBasenames імена файлів (*.mdc) з .cursor/rules
+ * @param {{ name: string }[]} skillItems рядки для секції Skills
+ * @param {{ name: string }[]} commandItems рядки для секції commands
+ * @returns {string} готовий вміст AGENTS.md без подвійних порожніх рядків у списках
+ */
+export function renderAgentsTemplate(templateText, mdcBasenames, skillItems, commandItems) {
+  let result = templateText
+  const serviceItems = mdcBasenames.map(mdcName => ({
+    name: `- .cursor/rules/${mdcName}`
+  }))
+  result = expandMustacheSection(result, 'services', serviceItems, 'name')
+  result = expandMustacheSection(result, 'skills', skillItems, 'name')
+  result = expandMustacheSection(result, 'commands', commandItems, 'name')
+  return collapseMultipleBlankLines(result)
+}
+
+/**
+ * Збирає markdown з рядків, прибираючи подвійні порожні рядки на стиках секцій.
+ * @param {string[]} lines рядки документа
+ * @returns {string} зібраний markdown із завершальним `\n`
+ */
+export function formatGeneratedMarkdownLines(lines) {
+  const text = lines.join('\n')
+  const collapsed = collapseMultipleBlankLines(text)
+  return collapsed.endsWith('\n') ? collapsed : `${collapsed}\n`
+}