@nitra/cursor 5.1.0 → 5.2.0

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

@@ -0,0 +1,298 @@
+/** @see ./docs/docgen-scan.md */
+// eslint-disable-next-line unicorn/import-style
+import path from 'node:path'
+import { existsSync, readdirSync, statSync } from 'node:fs'
+import { execFileSync } from 'node:child_process'
+import { once } from 'node:events'
+import { env } from 'node:process'
+
+import { isRunAsCli } from '../../../scripts/cli-entry.mjs'
+import { isDocgenIgnored } from './docgen-ignore.mjs'
+import { QUALITY_THRESHOLD, readDocQuality, staleness } from './docgen-crc.mjs'
+
+/** Кодові розширення, для яких генеруємо документацію. */
+const SOURCE_EXTENSIONS = new Set(['.js', '.mjs', '.ts', '.vue', '.py'])
+
+/** `*.test.*`, `*.spec.*` — тести, документувати не треба. */
+const TEST_FILE_RE = /\.(?:test|spec)\.[^.]+$/u
+
+/** Поріг великого прогону для Stop-гейта: більше stale-файлів — не блокуємо. */
+const DEFAULT_GATE_MAX = Number(env.N_CURSOR_DOC_FILES_GATE_MAX ?? 50) || 50
+
+/**
+ * Чи корінь має system-wide docs layout.
+ * Такий корінь зарезервований під репозиторні docs/adr, docs/explanation тощо,
+ * тому file-level docs у нього не пишемо.
+ * @param {string} root абсолютний корінь обходу
+ * @returns {boolean} true — корінь system-wide docs
+ */
+function isSystemWideDocsRoot(root) {
+  return existsSync(path.join(root, 'docs', 'adr')) || existsSync(path.join(root, 'docs', 'explanation'))
+}
+
+/**
+ * Чи є файл кодовим джерелом для документування.
+ * @param {string} fileName базове ім'я файлу
+ * @returns {boolean} true — документуємо; false — пропускаємо
+ */
+export function isSourceFile(fileName) {
+  if (fileName.endsWith('.d.ts')) return false
+  if (TEST_FILE_RE.test(fileName)) return false
+  return SOURCE_EXTENSIONS.has(path.extname(fileName))
+}
+
+/**
+ * Обчислює шлях md-документа для кодового файлу: тека `docs/` поряд із джерелом.
+ * Якщо `sourcePath` відносний, `docPath` теж відносний; якщо абсолютний — абсолютний.
+ * @param {string} sourcePath шлях до джерела (відносний або абсолютний)
+ * @returns {string} шлях до `<dir>/docs/<stem>.md` у тому ж просторі шляхів
+ */
+export function docPathForSource(sourcePath) {
+  const dir = path.dirname(sourcePath)
+  const stem = path.basename(sourcePath, path.extname(sourcePath))
+  return path.join(dir, 'docs', `${stem}.md`)
+}
+
+/**
+ * Чи кодовий файл `relPath` (posix, від кореня) підлягає документуванню:
+ * правильне розширення, не тест, не в ignore-дереві, не кореневий system-wide docs.
+ * @param {string} root абсолютний корінь
+ * @param {string} relPath posix-шлях файлу від кореня
+ * @returns {boolean} true — кандидат на доку
+ */
+export function isDocCandidate(root, relPath) {
+  const fileName = path.posix.basename(relPath)
+  if (!isSourceFile(fileName)) return false
+  if (isSystemWideDocsRoot(root) && path.posix.dirname(relPath) === '.') return false
+  return !isDocgenIgnored(relPath)
+}
+
+/**
+ * Описує один кодовий файл: шлях джерела, шлях доки, стан застарілості за CRC.
+ * @param {string} root абсолютний корінь
+ * @param {string} sourcePath posix-шлях джерела від кореня
+ * @returns {{sourcePath:string, docPath:string, stale:boolean, reason:'missing'|'crc-mismatch'|null}} опис файлу
+ */
+export function describeFile(root, sourcePath) {
+  const docPath = docPathForSource(sourcePath)
+  const { stale, reason } = staleness(path.join(root, sourcePath), path.join(root, docPath))
+  return { sourcePath, docPath, stale, reason }
+}
+
+/**
+ * Рекурсивно обходить дерево від `root`, повертає кодові файли зі станом застарілості.
+ * Синхронний `readdirSync` — детермінований порядок без гонок; обсяг дерева це дозволяє.
+ * @param {string} root абсолютний корінь обходу
+ * @returns {Array<{sourcePath:string, docPath:string, stale:boolean, reason:'missing'|'crc-mismatch'|null}>} кандидати з відносними шляхами
+ */
+export function scanForDocFiles(root) {
+  const results = []
+
+  /** @param {string} dir поточний каталог обходу */
+  function walk(dir) {
+    let entries
+    try {
+      entries = readdirSync(dir, { withFileTypes: true })
+    } catch {
+      return
+    }
+    for (const entry of entries) {
+      const fullPath = path.join(dir, entry.name)
+      const relPath = path.relative(root, fullPath)
+      if (entry.isDirectory()) {
+        if (isDocgenIgnored(relPath, 'dir')) continue
+        walk(fullPath)
+      } else if (entry.isFile() && isSourceFile(entry.name)) {
+        if (isSystemWideDocsRoot(root) && path.dirname(relPath) === '.') continue
+        const sourcePath = relPath.split(path.sep).join('/')
+        if (isDocgenIgnored(sourcePath)) continue
+        results.push(describeFile(root, sourcePath))
+      }
+    }
+  }
+
+  walk(root)
+  return results
+}
+
+/**
+ * Парсить `--root <dir>` з argv; default — cwd.
+ * @param {string[]} argv аргументи після підкоманди
+ * @returns {string} абсолютний корінь
+ */
+export function resolveRoot(argv) {
+  const i = argv.indexOf('--root')
+  return i !== -1 && argv[i + 1] ? path.resolve(argv[i + 1]) : process.cwd()
+}
+
+/**
+ * Сканує дерево і друкує JSON-масив усіх кодових файлів зі станом застарілості.
+ * Рішення «генерувати лише stale чи всі» приймає скіл, фільтруючи поле `stale`.
+ * @param {string[]} argv аргументи після назви субкоманди
+ * @returns {number} exit-код: 0 — успіх, 1 — корінь не існує
+ */
+export function runDocFilesScanCli(argv) {
+  const root = resolveRoot(argv)
+  if (!existsSync(root) || !statSync(root).isDirectory()) {
+    console.error(`doc-files scan: корінь не існує або не є директорією: ${root}`)
+    return 1
+  }
+  console.log(JSON.stringify(scanForDocFiles(root), null, 2))
+  return 0
+}
+
+/**
+ * Зчитує stdin до EOF як utf8 рядок. На TTY — повертає `''` одразу.
+ * @returns {Promise<string>} вміст stdin
+ */
+async function readStdin() {
+  if (process.stdin.isTTY) return ''
+  process.stdin.setEncoding('utf8')
+  const chunks = []
+  process.stdin.on('data', chunk => chunks.push(chunk))
+  try {
+    await once(process.stdin, 'end')
+  } catch {
+    // 'error' на stdin — повертаємо те, що встигли зібрати
+  }
+  return chunks.join('')
+}
+
+/**
+ * Дістає `tool_input.file_path` зі stdin JSON Claude Code PostToolUse hook.
+ * @param {string} stdinJson сирий вміст stdin
+ * @returns {string|null} відносний шлях або null
+ */
+function extractHookFilePath(stdinJson) {
+  if (!stdinJson) return null
+  try {
+    const fp = JSON.parse(stdinJson)?.tool_input?.file_path
+    return typeof fp === 'string' && fp !== '' ? fp : null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Список змінених у задачі джерел — найшвидший спосіб: `git diff --name-only HEAD`
+ * (working-tree проти HEAD). Допускаємо неповне покриття (закомічене в межах задачі
+ * випадає) — це свідомий компроміс; CRC лишається джерелом правди про застарілість.
+ * @param {string} root абсолютний корінь
+ * @returns {string[]} posix-шляхи кодових файлів-кандидатів, що існують
+ */
+function gitChangedSources(root) {
+  let out
+  try {
+    out = execFileSync('git', ['diff', '--name-only', 'HEAD'], { cwd: root, encoding: 'utf8' })
+  } catch {
+    return []
+  }
+  return out
+    .split('\n')
+    .map(s => s.trim())
+    .filter(rel => rel && isDocCandidate(root, rel) && existsSync(path.join(root, rel)))
+}
+
+/**
+ * Нормалізує абсолютний/відносний шлях до posix-шляху від кореня (або null поза деревом).
+ * @param {string} root абсолютний корінь
+ * @param {string} candidate шлях-кандидат
+ * @returns {string|null} posix-шлях від кореня
+ */
+function toRelSource(root, candidate) {
+  const rel = path.relative(root, path.resolve(root, candidate))
+  if (rel.startsWith('..') || path.isAbsolute(rel)) return null
+  return rel.split(path.sep).join('/')
+}
+
+/**
+ * `doc-files check --degraded` — інформаційний список свіжих за CRC док зі
+ * `score < QUALITY_THRESHOLD` (локальний конвеєр не дотягнув; ADR 260610-2228).
+ * Не блокує (exit 0): degraded — борг для `gen --retry-degraded`, а не гейт.
+ * @param {string} root абсолютний корінь
+ * @returns {number} exit-код: завжди 0
+ */
+function runDegradedReport(root) {
+  const degraded = []
+  for (const f of scanForDocFiles(root)) {
+    if (f.stale) continue
+    const { score, issues } = readDocQuality(path.join(root, f.docPath))
+    if (score !== null && score < QUALITY_THRESHOLD) degraded.push({ ...f, score, issues })
+  }
+  if (degraded.length === 0) {
+    console.log(`✓ doc-files: degraded-док немає (поріг ${QUALITY_THRESHOLD}).`)
+    return 0
+  }
+  const list = degraded
+    .map(f => {
+      const issuesTxt = f.issues.length ? ': ' + f.issues.join(',') : ''
+      return `  - ${f.sourcePath} (score=${f.score}${issuesTxt})`
+    })
+    .join('\n')
+  console.log(
+    `⚠ doc-files: degraded-док ${degraded.length} (score < ${QUALITY_THRESHOLD}):\n${list}\n→ перегенеруй: npx @nitra/cursor doc-files gen --retry-degraded`
+  )
+  return 0
+}
+
+/**
+ * `doc-files check` — детермінований детектор застарілості для hook'ів і CLI.
+ *
+ * Режими:
+ * - `--hook`     — PostToolUse: бере `file_path` зі stdin JSON, перевіряє один файл.
+ * - `--git`      — Stop-гейт: перевіряє `git diff --name-only HEAD`. Поріг `--max N`
+ *                  (default 50): якщо stale більше — не блокуємо (exit 0 + попередження).
+ * - `--degraded` — інформаційний звіт по доках зі score нижче порогу (exit 0).
+ * - `<paths…>`   — явні шляхи-джерела.
+ *
+ * Exit 2 (стале знайдено) — для hook'а це блок/нагадування Claude; exit 0 — все свіже
+ * або великий прогін понад поріг.
+ * @param {string[]} argv аргументи після назви субкоманди
+ * @returns {Promise<number>} exit-код (0 / 2)
+ */
+export async function runDocFilesCheckCli(argv) {
+  const root = resolveRoot(argv)
+  if (argv.includes('--degraded')) return runDegradedReport(root)
+  const hookMode = argv.includes('--hook')
+  const gitMode = argv.includes('--git')
+  const maxIdx = argv.indexOf('--max')
+  const gateMax = maxIdx !== -1 && argv[maxIdx + 1] ? Number(argv[maxIdx + 1]) || DEFAULT_GATE_MAX : DEFAULT_GATE_MAX
+
+  let sources
+  if (hookMode) {
+    const fp = extractHookFilePath(await readStdin())
+    const rel = fp ? toRelSource(root, fp) : null
+    sources = rel && isDocCandidate(root, rel) && existsSync(path.join(root, rel)) ? [rel] : []
+  } else if (gitMode) {
+    sources = gitChangedSources(root)
+  } else {
+    sources = argv
+      .filter(a => !a.startsWith('--') && a !== argv[maxIdx + 1])
+      .map(a => toRelSource(root, a))
+      .filter(rel => rel && isDocCandidate(root, rel) && existsSync(path.join(root, rel)))
+  }
+
+  const stale = sources.map(src => describeFile(root, src)).filter(f => f.stale)
+  if (stale.length === 0) return 0
+
+  // Великий прогін: Stop-гейт не блокує, лише попереджає (захист від нескінченного блоку).
+  if (gitMode && stale.length > gateMax) {
+    console.error(
+      `⚠ doc-files: застарілих док ${stale.length} (> ${gateMax}) — гейт не блокує. Запусти масовий прогін:\n  npx @nitra/cursor doc-files gen`
+    )
+    return 0
+  }
+
+  const list = stale.map(f => `  - ${f.sourcePath} (${f.reason})`).join('\n')
+  console.error(
+    `✗ doc-files: документація застаріла/відсутня для ${stale.length} файл(ів):\n${list}\n→ перегенеруй: /doc-files`
+  )
+  return 2
+}
+
+if (isRunAsCli(import.meta.url)) {
+  // Прямий запуск: `node skills/doc-files/js/docgen-scan.mjs [scan|check] [args]`
+  const [sub, ...rest] = process.argv.slice(2)
+  const argv = sub === 'scan' || sub === 'check' ? rest : process.argv.slice(2)
+  process.exitCode = sub === 'check' ? await runDocFilesCheckCli(argv) : runDocFilesScanCli(argv)
+}

package/skills/doc-files/js/docs/docgen-crc.md

@@ -0,0 +1,32 @@
+---
+docgen:
+  source: npm/skills/doc-files/js/docgen-crc.mjs
+  crc: 54e8e12b
+---
+
+# docgen-crc
+
+## Огляд
+
+Детермінований маркер актуальності файлових док: контрольна сума джерела у frontmatter плюс опційний degraded-маркер якості. Єдине джерело правди про «дока свіжа/застаріла/неякісна» для генерації, перевірок і хуків.
+
+## Поведінка
+
+1. Контрольна сума обчислюється з байтів джерела і записується у машинний frontmatter доки разом зі шляхом джерела; розбіжність суми з поточним джерелом (або відсутність доки) означає застарілість.
+2. Якщо генерація не дотягнула до порогу якості, frontmatter додатково несе оцінку (`score`) і коди проблем (`issues`); коди нормалізуються до YAML-безпечних (без пробілів, обмежена кількість), а старі доки без цих полів лишаються валідними.
+3. Поріг degraded — `70`, override через `N_CURSOR_DOC_FILES_THRESHOLD`.
+4. Перештампування знімає наявний frontmatter і ставить свіжий, не торкаючись тіла документа; якість при цьому передається явно — без неї поля якості зникають.
+
+## Публічний API
+
+- `crc32` — контрольна сума вмісту в hex.
+- `staleness` — стан доки відносно джерела: `missing` / `crc-mismatch` / свіжа.
+- `parseDocFrontmatter` / `buildDocFrontmatter` / `stampDoc` — читання і (пере)штампування машинного блока.
+- `readDocCrc` / `readDocQuality` — точкове читання суми та якості з доки.
+- `QUALITY_THRESHOLD` — чинний поріг degraded.
+
+## Гарантії поведінки
+
+- Сума не залежить від git-стану: rebase, гілки й незакомічені зміни на неї не впливають.
+- Frontmatter — єдиний машинний виняток із правила «чистий Markdown»; тіло доки модуль не редагує.
+- Відсутні поля якості читаються як «не оцінено» (`score: null`), а не як нуль.

package/skills/doc-files/js/docs/docgen-extract-anchors.md

@@ -0,0 +1,27 @@
+---
+docgen:
+  source: npm/skills/doc-files/js/docgen-extract-anchors.mjs
+  crc: e80e0827
+---
+
+# docgen-extract-anchors
+
+## Огляд
+
+Детермінований витяг «анкорів» — конкретних фрагментів коду, які модель зобов'язана згадати в документації, щоб не зісковзнути на generic-фрази. Анкори підставляються у промпти окремим блоком обов'язкового включення, а їх покриття перевіряється скорером.
+
+## Поведінка
+
+1. З тексту джерела збираються п'ять категорій анкорів: усі URL; експортовані константи-рядки з непорожнім значенням; маркери повідомлень про помилки виду `(rule.mdc)`; посилання на json-конфіги проєкту; code-block-приклади з провідного коментаря файлу (де автор зазвичай показує контракт).
+2. Кожна категорія дедуплікується зі збереженням порядку появи.
+3. Для промпта анкори форматуються в компактний текстовий блок з інструкціями, де саме їх згадати; якщо анкорів немає взагалі — блок не додається, щоб не вводити модель в оману «обов'язковими» полями.
+
+## Публічний API
+
+- `extractAnchors` — текст джерела → категоризовані анкори.
+- `anchorsToPrompt` — анкори → текстовий блок для system-промпта або порожній рядок.
+
+## Гарантії поведінки
+
+- Повністю детермінований і read-only; жодних LLM-викликів і мережі.
+- Працює по сирому тексту без AST: дешево і свідомо толерує надлишок (зайвий анкор — менша проблема, ніж пропущений).

package/skills/doc-files/js/docs/docgen-extract.md

@@ -0,0 +1,29 @@
+---
+docgen:
+  source: npm/skills/doc-files/js/docgen-extract.mjs
+  crc: 26bb2901
+---
+
+# docgen-extract
+
+## Огляд
+
+Детермінований екстрактор фактів про кодовий файл (нуль токенів): з тексту джерела збирається факт-лист, на якому конвеєр будує промпти, маркери поведінки й список заборонених до згадки внутрішніх імен.
+
+## Поведінка
+
+1. Провідний блок-коментар файлу (до першого коду) стає «наміром файлу»; з документувальних коментарів перед кожним експортом витягуються опис, параметри та опис повернення, відкидаючи беззмістовні заглушки.
+2. Збираються всі експортовані оголошення з безпосередньо передуючими їм коментарями.
+3. Імпорти класифікуються на stdlib / npm / внутрішні; імена символів, імпортованих із внутрішніх модулів, складають список internalSymbols — модель не має згадувати їх у доці, а скорер штрафує за витік.
+4. Маркери поведінки визначаються евристиками по тексту: read-only (немає запису у файлову систему), перехоплення помилок, повернення false/null при невдачі, звертання до мережі, кешування, свідомі пропуски шляхів.
+5. Для розширень поза js/mjs/ts повертається позначка unsupported — конвеєр переходить на one-shot-шлях.
+
+## Публічний API
+
+- `extractFacts` — головна точка: текст джерела + шлях → факт-лист `{header, exports, imports, internalSymbols, markers}` або `{unsupported: true}`.
+
+## Гарантії поведінки
+
+- Повністю детермінований: однаковий вхід → однаковий факт-лист; жодних LLM-викликів і мережі.
+- Read-only: файл не виконує операцій запису у файлову систему.
+- Евристики свідомо толерують надлишок (зайвий маркер — менша проблема, ніж пропущений).

package/skills/doc-files/js/docs/docgen-files-batch.md

@@ -0,0 +1,25 @@
+---
+docgen:
+  source: npm/skills/doc-files/js/docgen-files-batch.mjs
+  crc: 20a14675
+---
+
+# docgen-files-batch
+
+## Огляд
+
+CLI-оркестратор масової генерації файлових док (`doc-files gen` / `doc-files stamp`): черга, вибір цілей, preflight локального сервера, запис док зі свіжою контрольною сумою і degraded-маркером. Уся важка робота живе тут, а не в контексті агента.
+
+## Поведінка
+
+1. Дерево проєкту сканується, цілі обираються за режимом: за замовчуванням — застарілі доки; `--overwrite` — усі; `--retry-degraded` — свіжі за сумою, але з оцінкою нижче порогу. Зріз великого прогону — `--from N --limit M`.
+2. Перед генерацією — preflight локального сервера: «сервер лежить», «модель не влазить у пам'ять зайнятої машини» чи «потрібен API-ключ» зупиняють прогін одним зрозумілим повідомленням замість лавини помилок по файлах.
+3. Кожна ціль генерується локальним конвеєром; дока пишеться поряд із джерелом у `docs/` зі свіжою сумою. Якщо оцінка нижча за поріг — у frontmatter додаються оцінка й коди проблем, файл рахується як degraded.
+4. Підсумок: кількість успішних, degraded і помилкових файлів; за наявності degraded — підказка про `--retry-degraded`. Помилка хоча б одного файлу → exit-код `1`.
+5. `stamp` детерміновано перештамповує frontmatter у наявних доках без LLM (міграція док без суми), зберігаючи наявні поля якості.
+
+## Гарантії поведінки
+
+- Жодних хмарних викликів: збій локальної генерації стає помилкою чи degraded-маркером, а не ескалацією.
+- Доки пишуться атомарно по файлу: успішні цілі не відкочуються через подальші збої.
+- Прогін ніколи не комітить — рішення про фіксацію приймає користувач.

package/skills/doc-files/js/docs/docgen-gen.md

@@ -0,0 +1,30 @@
+---
+docgen:
+  source: npm/skills/doc-files/js/docgen-gen.mjs
+  crc: 2d6e5f79
+---
+
+# docgen-gen
+
+## Огляд
+
+Генератор однієї файлової доки local-only конвеєра: файл → українська поведінкова md-документація локальною моделлю, з детермінованим скорингом і позначкою degraded замість будь-яких хмарних ескалацій.
+
+## Поведінка
+
+1. З джерела детерміновано витягуються факти (намір файлу, експорти, маркери поведінки) та анкори (URL, константи, маркери помилок, конфіги, приклади з header-коментаря) — без жодного токена.
+2. Для підтримуваних структур документ збирається посекційно окремими викликами моделі: «Огляд» — лише з фактів, «Поведінка» — єдина секція з кодом у вікні, «Публічний API» — зі списку експортів; «Гарантії поведінки» — детермінований шаблон із маркерів без LLM. Для непідтримуваних структур (`vue`/`py` до появи юніт-шару) — один виклик на весь документ без скорингу.
+3. Чорнетки секцій проходять детермінований пост-лінт (зрізання сигнатур, обгорток, випадкових заголовків); найвразливіші секції — один цикл критика-редактора.
+4. Зібраний документ оцінюється детермінованим скорером (наявність огляду, змістовність поведінки, галюцинація кешу, витік внутрішніх імен). Якщо оцінка нижча за поріг — один повторний прогін з вищою температурою, перемагає кращий за оцінкою (вимикається `N_CURSOR_DOCGEN_BEST_OF=0`).
+5. Результат повертається з оцінкою, списком проблем і прапором degraded; рішення про повторну генерацію приймає batch-обгортка або користувач — конвеєр ніколи не звертається до хмари.
+
+## Публічний API
+
+- `generateDoc` — головна точка: шлях файлу → `{ md, ms, score, issues, degraded, model }`.
+- `DEFAULT_LOCAL_MODEL` — модель конвеєра: `N_CURSOR_DOCGEN_MODEL` → каскад локальних тирів → локальний omlx-дефолт напряму.
+
+## Гарантії поведінки
+
+- Local-only: жодних хмарних викликів і pre-route за складністю — будь-який файл генерується локальною моделлю.
+- Скоринг і пост-лінт детерміновані: однаковий вхід → однакова оцінка.
+- Помилка транспорту прокидається назовні — не маскується під degraded.

package/skills/doc-files/js/docs/docgen-prompts.md

@@ -0,0 +1,32 @@
+---
+docgen:
+  source: npm/skills/doc-files/js/docgen-prompts.mjs
+  crc: c454d2a6
+---
+
+# docgen-prompts
+
+## Огляд
+
+Промптовий шар local-only конвеєра файлових док: будує messages-набори для секційної генерації, критики й переписування, а секцію «Гарантії поведінки» формує детерміновано без LLM. Весь стиль документа (українська, поведінковість, заборона сигнатур) зашитий у спільний system-блок.
+
+## Поведінка
+
+1. Для кожної секції збирається мінімальний контекст: «Огляд» — лише людиночитний витяг фактів (без коду), «Поведінка» — єдина секція з повним кодом файлу у вікні, «Публічний API» — лише список експортів з їхніми описами. Анкори (URL, константи, маркери, приклади) додаються окремим блоком, коли вони є.
+2. Факт-лист перекладається в негативні й позитивні твердження для моделі: свідомі пропуски шляхів, read-only, перехоплення помилок, явне «Кешування: НЕМАЄ — не згадуй кеш» — щоб відсікти типові галюцинації ще в промпті.
+3. Критик отримує чорнетку секції і закритий список критеріїв дефектів (generic-фрази, пропущені анкори, граматика, підзаголовки, скопійовані сигнатури, вигадані факти); відповідь — список проблем або `NONE`. Переписувач отримує чорнетку разом зі списком проблем і повертає лише оновлений текст.
+4. «Гарантії поведінки» складаються шаблоном з маркерів факт-листа (read-only, fail-safe, кешування, пропуски шляхів, відсутність мережі) — нуль запитів і нуль generic-фраз; за відсутності маркерів — твердження про детермінованість.
+
+## Публічний API
+
+- `sectionMessages` — секційні набори messages з мінімальним контекстом під кожну секцію.
+- `criticMessages` / `refineMessages` — пара критика й переписувача для одного циклу уточнення секції.
+- `guaranteesFromMarkers` — детермінований текст секції гарантій з маркерів.
+- `oneShotMessages` — один запит на весь документ для нестандартних структур файлів.
+- `STYLE` — спільний system-блок стилю.
+
+## Гарантії поведінки
+
+- Код файлу потрапляє лише у промпт секції «Поведінка» й у one-shot — решта секцій працюють на факт-листі.
+- Формування промптів детерміноване: однакові факти й код → однакові messages.
+- Не звертається до мережі й не виконує LLM-викликів — лише будує тексти.

package/skills/doc-files/js/docs/docgen-scan.md

@@ -0,0 +1,25 @@
+---
+docgen:
+  source: npm/skills/doc-files/js/docgen-scan.mjs
+  crc: b517ab25
+---
+
+# docgen-scan
+
+## Огляд
+
+Сканер кодових файлів і детектор стану файлових док: які джерела підлягають документуванню, де лежить їхня дока, що застаріло, що degraded. Працює і як бібліотека для batch-генерації, і як CLI (`doc-files scan` / `doc-files check`) для хуків.
+
+## Поведінка
+
+1. Рекурсивний обхід від кореня збирає кодові файли (`js`/`mjs`/`ts`/`vue`/`py`), пропускаючи тести, оголошення типів, ignore-дерева і теки `docs/`; для кореня з system-wide docs-layout файлові доки на верхньому рівні не плануються.
+2. Для кожного джерела обчислюється шлях доки (`<dir>/docs/<stem>.md`) і стан застарілості за контрольною сумою.
+3. `check` працює в режимах: `--hook` — один файл зі stdin-payload редакторського хука; `--git` — змінені відносно HEAD джерела як Stop-гейт із порогом великого прогону (`--max`, дефолт `50` або `N_CURSOR_DOC_FILES_GATE_MAX`: більше застарілих — попередження без блоку); явні шляхи — точкова перевірка.
+4. Застарілі доки → exit-код `2` зі списком і підказкою перегенерації; усе свіже або великий прогін — `0`.
+5. `check --degraded` — інформаційний звіт (exit `0`): свіжі за сумою доки з оцінкою нижче порогу, з кодами проблем і підказкою про `gen --retry-degraded`. Degraded — видимий борг, не гейт.
+
+## Гарантії поведінки
+
+- Сканер read-only: жодних записів у дерево.
+- Рішення «застаріла/свіжа» детерміноване і залежить лише від вмісту джерела й frontmatter доки.
+- Stop-гейт ніколи не блокує масовий перший прогін понад поріг — захист від нескінченного блокування задач.

package/skills/doc-files/meta.json

@@ -0,0 +1 @@
+{ "auto": "завжди", "worktree": false, "requireRoot": true }

package/skills/fix/js/docs/llm-worker.md

@@ -1,3 +1,9 @@
+---
+docgen:
+  source: npm/skills/fix/js/llm-worker.mjs
+  crc: 8317f878
+---
+
 # llm-worker.mjs
 
 ## Огляд

package/skills/fix/js/docs/orchestrator.md

@@ -1,3 +1,9 @@
+---
+docgen:
+  source: npm/skills/fix/js/orchestrator.mjs
+  crc: 8b7a7de5
+---
+
 # orchestrator.mjs
 
 ## Огляд

package/skills/fix/js/llm-worker.mjs

@@ -12,7 +12,7 @@ import { callOmlx, isOmlxModel } from '../../../lib/omlx.mjs'
 export const MODEL = env.N_CURSOR_FIX_MODEL ?? resolveModel('min')
 export const MODEL_HEAVY = env.N_CURSOR_FIX_MODEL_HEAVY ?? resolveModel('avg')
 
-const JSON_CODE_BLOCK_RE = /```(?:json)?\s*([\s\S]*?)```/
+const JSON_CODE_BLOCK_RE = /```(?:json)?[ \t]{0,8}\n?([\s\S]*?)```/
 
 /**
  * Витягує відносні шляхи файлів із violation output.
@@ -35,7 +35,7 @@ function extractFilePaths(output) {
   }
 
   // Патерн без workspace: просто path/to/file.ext або ./file.ext
-  const re = /(?:^|\s)(\.?[\w][\w./-]*\.(?:json|js|mjs|ts|vue|yml|yaml|toml|mdc|md|sh|py))(?::\d+)?/gm
+  const re = /(?:^|\s)(\.?\w[\w./-]*\.(?:json|js|mjs|ts|vue|yml|yaml|toml|mdc|md|sh|py))(?::\d+)?/gm
   for (const m of output.matchAll(re)) {
     const p = m[1]
     if (!seen.has(p)) {
@@ -116,7 +116,7 @@ function callModel(prompt, model) {
         error: [
           `pi: немає ключа для ${provider}.`,
           `Встановіть N_CLOUD_MIN_MODEL=provider/model-id`,
-          `(напр.: openai/gpt-5.4-mini, google/gemini-2.5-flash, ollama/gemma3:4b)`,
+          `(напр.: openai/gpt-5.4-mini, google/gemini-2.5-flash, ollama/gemma3:4b)`
         ].join(' ')
       }
     }

package/skills/fix/js/orchestrator.mjs

@@ -20,7 +20,7 @@ export async function runOrchestratorCli(args, cwd) {
 
   const maxIterIdx = args.indexOf('--max-iter')
   const maxIter =
-    maxIterIdx === -1 ? DEFAULT_MAX_ITER : (Number(args[maxIterIdx + 1] ?? DEFAULT_MAX_ITER) || DEFAULT_MAX_ITER)
+    maxIterIdx === -1 ? DEFAULT_MAX_ITER : Number(args[maxIterIdx + 1] ?? DEFAULT_MAX_ITER) || DEFAULT_MAX_ITER
   const skipIdxs = new Set(maxIterIdx === -1 ? [] : [maxIterIdx, maxIterIdx + 1])
   const ruleFilter = args.filter((a, i) => !a.startsWith('-') && !skipIdxs.has(i))
 

package/skills/start-check/js/check.mjs

@@ -67,8 +67,8 @@ export async function scanStartWorkspaces(cwd) {
  * @param {string} log обʼєднаний stdout+stderr
  * @returns {{ready:boolean, firstError:string|null, logTail:string}} витяг
  */
-export function parseStartLog(log) {
-  const text = log ?? ''
+export function parseStartLog(log = '') {
+  const text = log
   const lines = text.split('\n')
   const firstError = lines.find(l => ERROR_RE.test(l))?.trim() ?? null
   const logTail = lines
@@ -137,7 +137,9 @@ export async function runWorkspaceStart(cwd, workspace, opts = {}) {
 
   // server: успіх = дожив до кінця grace (timedOut) або встиг віддати рядок готовності.
   // cli: успіх = чистий вихід 0 у межах grace.
-  const status = type === 'server' ? (timedOut || ready ? 'OK' : 'FAIL') : exitCode === 0 ? 'OK' : 'FAIL'
+  let status
+  if (type === 'server') status = timedOut || ready ? 'OK' : 'FAIL'
+  else status = exitCode === 0 ? 'OK' : 'FAIL'
 
   return {
     workspace,

package/skills/start-check/js/docs/check.md

@@ -1,3 +1,9 @@
+---
+docgen:
+  source: npm/skills/start-check/js/check.mjs
+  crc: 1809127a
+---
+
 # check.mjs
 
 ## Огляд