@nitra/cursor 3.17.0 → 3.18.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## [3.18.0] - 2026-06-03
+
+### Added
+
+- docgen: трирівнева генерація md-доки (CLI `docgen scan|modules` + скіл); скіл-специфічні скрипти тепер живуть у npm/skills/<id>/js/, синк копіює лише top-level SKILL.md (підкаталоги js/ пропускаються)
+
 ## [3.17.0] - 2026-06-02
 
 ### Added

package/bin/n-cursor.js

@@ -24,6 +24,8 @@
  *   `npx \@nitra/cursor lint-docker` — канонічний lint-docker (docker.mdc): `hadolint` по `Dockerfile`/`*.Dockerfile`
  *   `npx \@nitra/cursor lint-text`   — канонічний lint-text (text.mdc): `cspell` → `shellcheck` (з auto-fix) →
  *                                     `markdownlint-cli2 --fix` → `v8r` (json/json5/yaml/yml/toml)
+ *   `npx \@nitra/cursor docgen scan`    — детермінований JSON-лістинг кодових файлів для скілу docgen (тека `docs/` поряд із джерелом)
+ *   `npx \@nitra/cursor docgen modules` — детермінований JSON-лістинг логічних модулів (межі за `package.json`) для Tier 2 скілу docgen
  *   `npx \@nitra/cursor skill list`     — скіли пакета без синку в проєкт
  *   `npx \@nitra/cursor skill taze`     — промпт на stdout
  *   `npx \@nitra/cursor skill cursor taze ["task"]` — Cursor CLI (`cursor-agent -p`)
@@ -783,14 +785,17 @@ async function syncSkills(configSkills, bundledSkillsDir = BUNDLED_SKILLS_DIR) {
         await mkdir(destDir, { recursive: true })
         const meta = readSkillMetaRaw(srcDir)
         const worktree = meta?.worktree === true
-        const files = await readdir(srcDir)
-        for (const file of files) {
-          if (file === 'meta.json') continue
-          let content = await readFile(join(srcDir, file), 'utf8')
-          if (file === 'SKILL.md') {
+        const entries = await readdir(srcDir, { withFileTypes: true })
+        for (const entry of entries) {
+          // Лише top-level файли скіла. `meta.json` — метадані (не для споживача);
+          // підкаталоги (`js/` — скіл-специфічний код) виконуються з пакета через
+          // `npx`, у проєкт не копіюються (як `npm/rules/<id>/js/`). Див. scripts.mdc.
+          if (!entry.isFile() || entry.name === 'meta.json') continue
+          let content = await readFile(join(srcDir, entry.name), 'utf8')
+          if (entry.name === 'SKILL.md') {
             content = injectWorktreeNotice(content, worktree)
           }
-          await writeFile(join(destDir, file), content, 'utf8')
+          await writeFile(join(destDir, entry.name), content, 'utf8')
         }
         console.log(`✅`)
         success++
@@ -1580,6 +1585,22 @@ try {
 
       break
     }
+    case 'docgen': {
+      // n-cursor docgen scan|modules — детермінований лістинг для скілу docgen.
+      // scan — кодові файли; modules — логічні модулі (межі за package.json).
+      // Друкує JSON; генерацію доки робить скіл, диспатчачи субагентів.
+      const { runDocgenScanCli, runDocgenModulesCli } = await import('../skills/docgen/js/docgen-scan.mjs')
+      if (args[0] === 'scan') {
+        process.exitCode = await runDocgenScanCli(args.slice(1))
+      } else if (args[0] === 'modules') {
+        process.exitCode = await runDocgenModulesCli(args.slice(1))
+      } else {
+        console.error('Usage: npx @nitra/cursor docgen <scan|modules> [--root <dir>]')
+        process.exitCode = 1
+      }
+
+      break
+    }
     case undefined:
     case '': {
       await runSync()
@@ -1589,7 +1610,7 @@ try {
     default: {
       console.error(`❌ Невідома команда: ${command}`)
       console.error(
-        `   Очікується: (без аргументів) синхронізація правил, check, rename-yaml-extensions, post-tool-use-fix, lint, lint-ga, lint-rego, lint-k8s, lint-docker, lint-text, coverage, change, release, skill, worktree, lint-ci, flow, trace, graph`
+        `   Очікується: (без аргументів) синхронізація правил, check, rename-yaml-extensions, post-tool-use-fix, lint, lint-ga, lint-rego, lint-k8s, lint-docker, lint-text, coverage, change, release, skill, worktree, lint-ci, flow, trace, graph, docgen`
       )
       process.exitCode = 1
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nitra/cursor",
-  "version": "3.17.0",
+  "version": "3.18.0",
   "description": "CLI для завантаження cursor-правил (префікс n-) у локальний репозиторій",
   "keywords": [
     "cli",

package/skills/docgen/SKILL.md

@@ -0,0 +1,203 @@
+---
+name: docgen
+description: >-
+  Обходить проєкт і для кожного кодового файлу (js/mjs/ts/vue/py) пише вичерпну українську md-документацію у теку docs/ поряд із кодом — диспатчить окремого субагента на кожен файл, за правилами adr/ci4
+---
+
+# docgen — генерація документації по файлах
+
+## Мета
+
+Для кожного кодового файлу проєкту створити вичерпну `.md`-документацію у теці `docs/`
+**поряд із самим файлом** (`<dir>/docs/<stem>.md`). Документацію пише **окремий субагент**
+на кожен файл — не один прохід, а батч-диспатч. Джерело правди стилю — правила `adr` і
+`ci4` (`docs/explanation`/`docs/adr`-каталоги з тих правил **не застосовуємо** — доку
+кладемо локально поряд із кодом).
+
+Документація — **трирівнева**, рівні виконуються строго послідовно:
+
+1. **Tier 1 — файли**: `<dir>/docs/<stem>.md`, субагент на файл (нижче).
+2. **Tier 2 — module-summary**: `<module_root>/docs/ARCHITECTURE.md`, субагент на модуль.
+3. **Tier 3 — доменні доки**: `docs/<домен>.md` у кореневій `docs/`, субагент-синтезатор
+   виділяє бізнес-домени й пише файл на кожен домен.
+
+Агрегат ніколи не випереджає джерело: Tier 2 — лише після завершення всього Tier 1,
+Tier 3 — лише після завершення всього Tier 2.
+
+## ⚠️ Паралелізм
+
+Диспатч субагентів — **батчами по 5 одночасно**. Не запускати весь список одразу
+(перевантаження). Кожен субагент пише свій окремий файл — спільного стану немає, гонок
+за файли немає.
+
+Рівні строго послідовні: Tier 2 стартує лише після завершення всього Tier 1, Tier 3 —
+лише після всього Tier 2. Усередині Tier 1 і Tier 2 — батчі по 5. Tier 3 — один субагент.
+
+## Передумова
+
+- Поточна директорія — корінь проєкту, який документуємо.
+- Доступний `npx @nitra/cursor` (пакет `@nitra/cursor` встановлено або через npx).
+
+## Workflow
+
+### Крок 1: Зібрати список файлів
+
+```bash
+npx @nitra/cursor docgen scan
+```
+
+Команда друкує JSON-масив об'єктів:
+
+```json
+[
+  { "sourcePath": "/abs/src/lib/foo.js", "relSource": "src/lib/foo.js",
+    "docPath": "/abs/src/lib/docs/foo.md", "exists": false }
+]
+```
+
+Розпарси JSON.
+
+### Крок 2: Відфільтрувати вже описані
+
+За замовчуванням **пропусти** елементи з `"exists": true`. Перегенеровуй їх лише якщо
+користувач явно попросив `--overwrite` (тоді обробляй усі). `--overwrite` — **не** прапор
+`docgen scan`: scanner лише лістить файли, а рішення «пропустити чи перегенерувати» приймаєш
+ти тут, фільтруючи за полем `exists`.
+
+Якщо після фільтра список порожній — зупинись:
+
+```
+✓ Усі кодові файли вже мають документацію. Нічого робити.
+```
+
+Запам'ятай `total = довжина відфільтрованого списку`.
+
+### Крок 3: Диспатч субагентів батчами по 5
+
+Розбий список на батчі по 5 елементів. Для кожного батчу запусти **до 5 субагентів
+одночасно (в одному повідомленні)**, дочекайся завершення батчу, переходь до наступного.
+
+Промпт кожного субагента (підстав `sourcePath` і `docPath`):
+
+```
+Напиши вичерпну технічну документацію для одного файлу коду.
+
+ФАЙЛ-ДЖЕРЕЛО: <sourcePath>
+ЗАПИСАТИ В: <docPath>
+
+Кроки:
+1. Прочитай файл <sourcePath> повністю.
+2. Створи теку для <docPath>, якщо її немає.
+3. Запиши markdown-документ у <docPath> за правилами нижче.
+
+Правила документа (за adr/ci4):
+- Мова — УКРАЇНСЬКА для всього тексту (заголовки, абзаци, таблиці). Code identifiers,
+  шляхи, імена API, команди — лишай як у коді (зазвичай ASCII).
+- ЧИСТИЙ Markdown. Жодних HTML-обгорток (<div>/<span>/класів) — токен-ефективність.
+- Контекстна незалежність: кожна секція самодостатня. Явно повторюй імена сутностей
+  («функція `calculateTotal()`», «модуль `src/lib/foo.js`»). Заборонено «як вище»,
+  «ця функція», «той сервіс».
+- ВИЧЕРПНІСТЬ — опиши всю логіку файлу. Секції:
+  ## Огляд — призначення файлу, його роль, що дає.
+  ## Експорти / API — кожен експорт (функція/клас/компонент/константа).
+  ## Функції — для кожної: сигнатура, параметри (типи), що повертає, side effects.
+  ## Залежності — імпорти й зовнішні залежності та навіщо вони.
+  ## Потік виконання / Використання — як цей файл використовують; ключові гілки логіки.
+- Для .vue додай опис props, emits, slots, реактивного стану.
+- НЕ вигадуй деталей, яких немає в коді.
+- Мета — Rebuild Test: за цим документом можна відтворити логіку файлу.
+
+Поверни лише підтвердження, що файл <docPath> записано.
+```
+
+### Крок 4: Tier 2 — module-summary
+
+Після завершення **всіх** батчів Tier 1 зібрати список модулів:
+
+```bash
+npx @nitra/cursor docgen modules
+```
+
+Команда друкує JSON-масив:
+
+```json
+[
+  { "moduleRoot": "/abs/npm/rules/adr", "relRoot": "npm/rules/adr",
+    "slug": "npm-rules-adr", "docPath": "/abs/npm/rules/adr/docs/ARCHITECTURE.md",
+    "members": ["npm/rules/adr/index.mjs"], "exists": false }
+]
+```
+
+module-summary **завжди регенерується** (це агрегат — поле `exists` ігноруй). Розбий модулі на батчі по 5 і диспатч субагентів. Промпт кожного (підстав `relRoot`, `docPath`, `members`):
+
+```
+Напиши module-summary для одного логічного модуля.
+
+МОДУЛЬ: <relRoot>
+ЗАПИСАТИ В: <docPath>
+ФАЙЛИ МОДУЛЯ (members): <members>
+
+Кроки:
+1. Прочитай файлові доки членів модуля. <member> — relSource відносно кореня проєкту
+   (= поточний CWD); його файлова дока — <CWD>/<dir>/docs/<stem>.md. За потреби зазирни
+   в самі файли.
+2. Створи теку для <docPath>, якщо її немає.
+3. Запиши markdown у <docPath> за тими ж правилами стилю, що й файлова дока
+   (українська, чистий Markdown, контекстна незалежність, без HTML).
+
+Секції module-summary:
+## Огляд модуля — призначення модуля <relRoot>, його роль у проєкті.
+## Ключові файли — список із кліковими посиланнями (відносними до розташування цього
+   ARCHITECTURE.md) на члени модуля та їхні файлові доки.
+## Публічний API — що модуль експортує назовні.
+## Внутрішній потік — як компоненти модуля взаємодіють.
+## Підмодулі — вкладені модулі, якщо є.
+
+Поверни лише підтвердження, що файл <docPath> записано.
+```
+
+### Крок 5: Tier 3 — доменні доки
+
+Після завершення **всіх** module-summary диспатч **одного** субагента-синтезатора.
+У промпт підстав конкретний перелік шляхів module-summary (<module_root>/docs/ARCHITECTURE.md
+кожного модуля з виводу `docgen modules`), а не інструкцію їх шукати. Промпт:
+
+```
+Синтезуй доменну документацію бізнес-процесів проєкту.
+
+ДЖЕРЕЛА (module-summary, читай усі): <перелік шляхів ARCHITECTURE.md, підставлений вище>
+
+Кроки:
+1. Прочитай усі module-summary.
+2. Виділи бізнес-домени та процеси (можуть перетинати межі модулів). Доменів може бути багато.
+3. Для КОЖНОГО домену запиши окремий файл docs/<домен>.md у кореневій docs/:
+   - назва файлу — короткий kebab-slug домену;
+   - не перезаписуй файлові доки кореневих файлів у docs/ (напр. app.md, eslint.config.md):
+     якщо слаґ домену збігається з іменем такого файлу — додай суфікс -domain
+     (напр. app-domain.md). Інакше пиши docs/<домен>.md як є;
+   - опиши бізнес-процес домену з кліковими відносними посиланнями на module-summary, конкретні файли й директорії.
+
+Правила стилю — ті ж (українська, чистий Markdown, контекстна незалежність, без HTML).
+
+Поверни перелік створених файлів docs/<домен>.md.
+```
+
+### Крок 6: Підсумок
+
+Після всіх батчів виведи:
+
+```
+✓ docgen завершено.
+Tier 1 (файли): описано <N>, пропущено <S>, помилок <E>.
+Tier 2 (модулі): <M> module-summary.
+Tier 3 (домени): <D> доменних доків у docs/.
+```
+
+Перелічи файли з помилками (субагент впав або не записав `docPath`), якщо такі є.
+Помилка одного файлу не зупиняє решту — обробляй усі батчі до кінця.
+
+## Нотатки
+
+- Не комітити автоматично — користувач вирішує, коли комітити згенеровану доку.
+- Scanner ігнорує `node_modules`, `dist`, `.git`, `__pycache__`, `coverage`, `.cursor`,
+  `.claude`, усі теки `docs/`, а також `*.test.*` / `*.spec.*` / `*.d.ts`.

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

@@ -0,0 +1,232 @@
+/**
+ * docgen scanner — детермінований обхід проєкту для скілу `docgen`.
+ *
+ * Друкує JSON-список кодових файлів із обчисленим `docPath` (тека `docs/` поряд із
+ * джерелом). Рішення про overwrite/skip приймає скіл — scanner лише лістить і ставить
+ * прапор `exists`. LLM/мережі тут немає: уся генерація доки — у субагентах скілу.
+ */
+// eslint-disable-next-line unicorn/import-style
+import path from 'node:path'
+import { existsSync, readdirSync, statSync } from 'node:fs'
+
+import { isRunAsCli } from '../../../scripts/cli-entry.mjs'
+
+/** Кодові розширення, для яких генеруємо документацію. */
+const SOURCE_EXTENSIONS = new Set(['.js', '.mjs', '.ts', '.vue', '.py'])
+
+/** Теки, які scanner ніколи не заходить (включно з самими `docs/`). */
+const IGNORED_DIRS = new Set([
+  'node_modules', 'dist', '.git', '__pycache__', 'coverage', '.cursor', '.claude', 'docs'
+])
+
+/** `*.test.*`, `*.spec.*` — тести, документувати не треба. */
+const TEST_FILE_RE = /\.(?:test|spec)\.[^.]+$/u
+
+/**
+ * Чи є файл кодовим джерелом для документування.
+ * @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/` поряд із джерелом.
+ * @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`)
+}
+
+/**
+ * Рекурсивно обходить дерево від `root`, повертає кодові файли для документування.
+ * Синхронний `readdirSync` — детермінований порядок і простий рекурсивний обхід без
+ * гонок; обсяг дерева проєкту це дозволяє.
+ * @param {string} root абсолютний корінь обходу
+ * @returns {Array<{sourcePath:string, relSource:string, docPath:string, exists:boolean}>} список кандидатів
+ */
+export function scanForDocgen(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)
+      if (entry.isDirectory()) {
+        if (IGNORED_DIRS.has(entry.name)) continue
+        walk(fullPath)
+      } else if (entry.isFile() && isSourceFile(entry.name)) {
+        const docPath = docPathForSource(fullPath)
+        results.push({
+          sourcePath: fullPath,
+          relSource: path.relative(root, fullPath),
+          docPath,
+          exists: existsSync(docPath)
+        })
+      }
+    }
+  }
+
+  walk(root)
+  return results
+}
+
+/**
+ * Стабільний slug модуля з його відносного шляху (для лейблів/логів).
+ * @param {string} root абсолютний корінь обходу
+ * @param {string} moduleRoot абсолютний корінь модуля
+ * @returns {string} slug: `npm/rules/adr` → `npm-rules-adr`, корінь → `root`
+ */
+export function slugForModule(root, moduleRoot) {
+  const rel = path.relative(root, moduleRoot)
+  // корінь репо: фіксований sentinel 'root'
+  if (rel === '') return 'root'
+  return rel.split(path.sep).join('-').replaceAll(/[^\w-]+/gu, '-')
+}
+
+/**
+ * Знаходить корені модулів — теки з `package.json` (корінь завжди модуль).
+ * Ті ж IGNORED_DIRS, тож `package.json` у node_modules тощо не враховується.
+ * @param {string} root абсолютний корінь обходу
+ * @returns {string[]} абсолютні шляхи коренів модулів
+ */
+export function findModuleRoots(root) {
+  const roots = [root]
+
+  /** @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)
+      if (entry.isDirectory()) {
+        if (IGNORED_DIRS.has(entry.name)) continue
+        walk(fullPath)
+      } else if (entry.isFile() && entry.name === 'package.json' && dir !== root) {
+        roots.push(dir)
+      }
+    }
+  }
+
+  walk(root)
+  return roots
+}
+
+/**
+ * Найближчий модуль-предок для файлу (найдовший збіг шляху).
+ * @param {string} filePath абсолютний шлях до файлу
+ * @param {string[]} moduleRoots абсолютні корені модулів
+ * @returns {string|null} абсолютний корінь модуля або null
+ */
+export function nearestModuleRoot(filePath, moduleRoots) {
+  let best = null
+  for (const moduleRoot of moduleRoots) {
+    const rel = path.relative(moduleRoot, filePath)
+    if (rel.startsWith('..') || path.isAbsolute(rel)) continue
+    if (best === null || moduleRoot.length > best.length) best = moduleRoot
+  }
+  return best
+}
+
+/**
+ * Лістить логічні модулі проєкту з членами-файлами і docPath module-summary.
+ * Модулі без кодових файлів пропускаються.
+ * @param {string} root абсолютний корінь обходу
+ * @returns {Array<{moduleRoot:string, relRoot:string, slug:string, docPath:string, members:string[], exists:boolean}>} модулі (members — relSource-и, відносні від root)
+ */
+export function scanForModules(root) {
+  const files = scanForDocgen(root)
+  const moduleRoots = findModuleRoots(root)
+  const byRoot = new Map()
+  for (const file of files) {
+    const moduleRoot = nearestModuleRoot(file.sourcePath, moduleRoots)
+    if (moduleRoot === null) continue
+    if (!byRoot.has(moduleRoot)) byRoot.set(moduleRoot, [])
+    byRoot.get(moduleRoot).push(file.relSource)
+  }
+
+  const results = []
+  for (const moduleRoot of moduleRoots) {
+    const members = byRoot.get(moduleRoot)
+    if (!members || members.length === 0) continue
+    const docPath = path.join(moduleRoot, 'docs', 'ARCHITECTURE.md')
+    results.push({
+      moduleRoot,
+      relRoot: path.relative(root, moduleRoot) || '.',
+      slug: slugForModule(root, moduleRoot),
+      docPath,
+      members: members.toSorted(),
+      exists: existsSync(docPath)
+    })
+  }
+  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()
+}
+
+/**
+ * Парсить `--root <dir>` (default — cwd), сканує і друкує JSON-масив у stdout.
+ * @param {string[]} argv аргументи після назви субкоманди (наприклад ['--root', '<dir>'])
+ * @returns {Promise<number>} exit-код: 0 — успіх, 1 — корінь не існує
+ */
+export async function runDocgenScanCli(argv) {
+  const root = resolveRoot(argv)
+
+  if (!existsSync(root) || !statSync(root).isDirectory()) {
+    console.error(`docgen scan: корінь не існує або не є директорією: ${root}`)
+    return 1
+  }
+
+  const items = await scanForDocgen(root)
+  console.log(JSON.stringify(items, null, 2))
+  return 0
+}
+
+/**
+ * Парсить `--root`, сканує модулі і друкує JSON-масив у stdout.
+ * @param {string[]} argv аргументи після назви субкоманди (наприклад ['--root', '<dir>'])
+ * @returns {Promise<number>} exit-код: 0 — успіх, 1 — корінь не існує
+ */
+export async function runDocgenModulesCli(argv) {
+  const root = resolveRoot(argv)
+
+  if (!existsSync(root) || !statSync(root).isDirectory()) {
+    console.error(`docgen modules: корінь не існує або не є директорією: ${root}`)
+    return 1
+  }
+
+  const items = await scanForModules(root)
+  console.log(JSON.stringify(items, null, 2))
+  return 0
+}
+
+if (isRunAsCli(import.meta.url)) {
+  // Прямий запуск: `node skills/docgen/js/docgen-scan.mjs --root <dir>`
+  process.exitCode = await runDocgenScanCli(process.argv.slice(2))
+}

package/skills/docgen/meta.json

@@ -0,0 +1 @@
+{ "worktree": true }