@nitra/cursor 5.1.0 → 5.2.0

package/skills/docgen/SKILL.md

@@ -1,224 +0,0 @@
----
-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": "src/lib/foo.js", "docPath": "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>/класів) — токен-ефективність.
-- ФОКУС НА ПОВЕДІНЦІ, не реалізації. Пиши ЩО і НАВІЩО, а не як саме це зроблено.
-- НЕ перелічуй модулі стандартної бібліотеки (node:fs, node:path, node:crypto, python stdlib
-  тощо) — вони не несуть бізнес-значення. Зовнішні залежності (npm-пакети, внутрішні модулі)
-  згадуй лише якщо їхня роль не очевидна з контексту.
-- НЕ перелічуй внутрішні назви допоміжних функцій/змінних — описуй їхню роль і поведінку.
-  Імена публічних exports згадуй лише коли export — справжня точка інтеграції, яку кличуть
-  ззовні. Для дрібних/листкових модулів з однією відповідальністю опиши роль поведінково,
-  БЕЗ сигнатур, таблиць типів і переліку параметрів — це деталі реалізації.
-- Контекстна незалежність: кожна секція самодостатня. Уникай «як вище», «ця функція», «той сервіс».
-- Секції (включай лише доречні — порожніх не вигадуй):
-  ## Огляд — 1-3 речення: що файл робить і навіщо він існує (роль у системі). Згадай
-    ключову семантику, якщо вона визначає сенс файлу (opt-in/gate, кеш, ідемпотентність тощо).
-  ## Поведінка — покроковий алгоритм у бізнес-термінах (не деталі реалізації).
-    Нумерований список: що відбувається, умови, гілки логіки. Якщо файл керується
-    конфігом чи форматом даних — наведи короткий приклад (тільки реальний з коду).
-  ## Публічний API — ЛИШЕ якщо модуль має нетривіальну зовнішню поверхню, яку називають
-    споживачі. Для кожного export: назва + що робить. Без сигнатур і таблиць типів.
-    Не дублюй ## Поведінка. Для модуля з однією функцією-предикатом цю секцію пропусти.
-  ## Де використовується — де в системі цей файл вживається (якщо відомо з коду).
-  ## Гарантії поведінки — інваріанти й крайові випадки: що гарантовано (read-only,
-    не кидає винятків, fail-safe-значення за замовчуванням, безпечна обробка поганих даних)
-    і що стається при відсутніх ресурсах чи некоректному вводі. Пропусти, якщо таких гарантій немає.
-- Для .vue додай ## Інтерфейс компонента — props (типи, defaults), emits, slots, реактивний стан.
-- НЕ вигадуй деталей, яких немає в коді.
-- Мета — Behavior 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> — sourcePath відносно кореня проєкту
-   (= поточний 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`.
-  Кореневий repo `docs/` — system-wide only: file-level docs туди не пишуться, і Tier 1
-  має трактувати цей корінь як повністю нецільовий.
-- Список glob-ів для ignore живе в окремому snippet-модулі
-  `npm/skills/docgen/js/docgen-ignore.mjs` (`DOCGEN_IGNORE_GLOBS`).
-  Scanner лише читає цей список.

package/skills/docgen/bench/etalon/firebase_hosting.md

@@ -1,19 +0,0 @@
-# firebase_hosting.mjs
-
-## Огляд
-
-Перевірка-концерн правила abie: у підкаталогах першого рівня репозиторію не повинно бути артефактів Firebase Hosting (`.firebaserc`, `firebase.json`, `.firebase/`), бо `abie.mdc` забороняє Firebase Hosting. Сам корінь репозиторію не перевіряється — там ці імена можуть належати суміжним проєктам.
-
-## Поведінка
-
-1. Прочитати список елементів кореня репозиторію. Якщо каталог не читається — зафіксувати помилку (fail) і завершитися.
-2. Відібрати підкаталоги першого рівня, пропустивши `.git` і `node_modules`.
-3. У кожному такому підкаталозі перевірити наявність заборонених імен: файлів `.firebaserc`, `firebase.json` і каталогу `.firebase/`. Кожна знахідка — окремий fail.
-4. Якщо жодного порушення не знайдено — зафіксувати pass.
-5. Повернути підсумковий exit-код.
-
-## Гарантії поведінки
-
-- Read-only: лише перелічує й перевіряє існування шляхів.
-- Помилка читання кореня не валить процес винятком, а стає fail.
-- Перевіряється лише перший рівень; корінь і глибші рівні поза охопленням.

package/skills/docgen/bench/etalon/k8s-tree.md

@@ -1,24 +0,0 @@
-# k8s-tree.mjs
-
-## Огляд
-
-Обхід Kubernetes-дерева для перевірок abie з кешуванням на час одного прогону. Знаходить YAML під сегментом `k8s/` і визначає каталоги з `Deployment`. Перший виклик платить за обхід; наступні концерни прогону беруть із кешу.
-
-## Поведінка
-
-1. Пошук маніфестів: рекурсивно обійти дерево, відібравши `.yaml`/`.yml` під сегментом `k8s/`; `.github/` свідомо пропускається. Результат відсортований.
-2. Каталоги з Deployment: розпарсити передані YAML, відібрати `kind: Deployment`, зібрати унікальні каталоги.
-3. Кешування: обидві операції кешуються module-level singleton-ом за ключем із входів; повтор без I/O.
-4. Пошкоджені YAML за замовчуванням мовчки пропускаються; репортер передає викликач.
-
-## Публічний API
-
-- `findK8sYamlFiles` — відсортований список YAML під `k8s/` (з кешем, пропуск `.github/`).
-- `collectDeploymentDirs` — множина каталогів із Deployment (кеш, опц. репортер помилок).
-
-## Гарантії поведінки
-
-- Read-only щодо проєкту.
-- Стійкість до пошкоджених YAML: помилкові документи пропускаються, обхід не переривається.
-- Детермінований вивід (стабільне сортування).
-- Кеш у межах прогону; повторні виклики безкоштовні.

package/skills/docgen/bench/etalon/overlay-paths.md

@@ -1,24 +0,0 @@
-# overlay-paths.mjs
-
-## Огляд
-
-Набір чистих path-хелперів для overlay-перевірок правила abie: класифікація шляхів (ua-overlay проти base-шару), виведення каталогу пакета з overlay-шляху, умовні питання правила (чи потрібен HTTPRoute, чи є Deployment). Уся логіка — над рядками/шляхами та перевіркою існування файлів; YAML не парситься.
-
-## Поведінка
-
-- ua-overlay: шлях закінчується на `ua/kustomization.yaml`; base-шар — за сегментом `base/`.
-- Каталог пакета: з `…/k8s/ua/kustomization.yaml` виділяється батько `k8s/`; без збігу — немає результату.
-- HTTPRoute-gate: вимога лише для Vite-пакетів (є `vite.config.{js,mjs,ts}`).
-- Deployment: чи хоч один каталог із Deployment лежить у `k8s/` цього пакета.
-- base-шар: yaml під `<пакет>/k8s/` і не в `ua/`.
-- Шляхи нормалізуються до posix (`\`→`/`).
-
-## Публічний API
-
-- `isUaKustomizationPath`, `abiePackageDirFromK8sOverlay`, `abieOverlayRequiresHttpRouteByVite`, `abieOverlayK8sTreeHasDeployment`, `isAbieK8sBaseYamlPath`, `isK8sYamlInAbiePackageExcludingUaOverlay`.
-
-## Гарантії поведінки
-
-- Read-only, без побічних ефектів.
-- Невідповідність шаблону → негативний/порожній результат, не виняток.
-- Незалежність від ОС (розділювачі зводяться до `/`).

package/skills/docgen/js/docgen-batch-omlx.mjs

@@ -1,82 +0,0 @@
-/**
- * Тимчасовий A/B-batch: docgen Tier 1 через omlx (gemma-4-e2b 4bit на MLX)
- * замість pi/ollama. Перезаписує всі docs/<stem>.md для файлів з sym<4,
- * НЕ ескалює в cloud. Призначення — порівняння якості omlx vs попередньої версії.
- *
- * Запуск: node npm/skills/docgen/js/docgen-batch-omlx.mjs [--limit N] [--from N]
- *   --limit N — обробити перші N файлів зі списку sym<4
- *   --from N  — почати з індексу N (для дозапуску)
- */
-import { readFileSync, mkdirSync, writeFileSync } from 'node:fs'
-import { dirname, join, resolve } from 'node:path'
-import { fileURLToPath } from 'node:url'
-import { execSync } from 'node:child_process'
-import { env } from 'node:process'
-import { generateDoc } from './docgen-gen.mjs'
-import { extractFacts } from './docgen-extract.mjs'
-
-const ROOT = resolve(fileURLToPath(import.meta.url), '../../../../..')
-
-const args = process.argv.slice(2)
-const limitIdx = args.indexOf('--limit')
-const limit = limitIdx !== -1 ? Number(args[limitIdx + 1]) : Infinity
-const fromIdx = args.indexOf('--from')
-const from = fromIdx !== -1 ? Number(args[fromIdx + 1]) : 0
-
-env.N_CURSOR_DOCGEN_BACKEND = 'omlx'
-
-const scanOut = execSync('node npm/bin/n-cursor.js docgen scan', { cwd: ROOT, encoding: 'utf8' })
-const all = JSON.parse(scanOut)
-
-const local = []
-for (const f of all) {
-  try {
-    const src = readFileSync(join(ROOT, f.sourcePath), 'utf8')
-    const facts = extractFacts(src, join(ROOT, f.sourcePath))
-    const sym = (facts.internalSymbols ?? []).length
-    if (sym < 4) local.push({ ...f, sym })
-  } catch {
-    /* пропускаємо нечитані */
-  }
-}
-
-const slice = local.slice(from, from + limit)
-console.log(`📋 Файлів sym<4 у проєкті: ${local.length}; обробляємо: ${slice.length} (from=${from}, limit=${limit === Infinity ? 'усе' : limit})`)
-console.log(`🤖 Бекенд: omlx → ${env.N_CURSOR_DOCGEN_OMLX_URL ?? 'http://127.0.0.1:8000/v1/chat/completions'}`)
-
-const stats = { ok: 0, err: 0, totalMs: 0, scores: [], errors: [] }
-
-for (let i = 0; i < slice.length; i++) {
-  const f = slice[i]
-  const t0 = Date.now()
-  const pct = Math.round(((i + 1) / slice.length) * 100)
-  process.stdout.write(`  [${i + 1}/${slice.length} ${pct}%] sym=${f.sym} ${f.sourcePath} ... `)
-  try {
-    const result = await generateDoc(join(ROOT, f.sourcePath), {
-      symThreshold: 999, // не уходити в cloud за sym
-      cloudModel: null // повністю вимкнути cloud-fallback навіть при low det-score
-    })
-    const docAbs = join(ROOT, f.docPath)
-    mkdirSync(dirname(docAbs), { recursive: true })
-    writeFileSync(docAbs, result.md)
-    const ms = Date.now() - t0
-    stats.ok++
-    stats.totalMs += ms
-    stats.scores.push(result.score ?? 0)
-    process.stdout.write(`✓ ${Math.round(ms / 1000)}s score=${result.score ?? '?'} tier=${result.tier}\n`)
-  } catch (error) {
-    stats.err++
-    stats.errors.push({ path: f.sourcePath, msg: error.message })
-    process.stdout.write(`✗ ${error.message}\n`)
-  }
-}
-
-const avgScore = stats.scores.length ? Math.round(stats.scores.reduce((a, b) => a + b, 0) / stats.scores.length) : 0
-console.log(`\n${'─'.repeat(60)}`)
-console.log(`✓ OK: ${stats.ok}  ✗ Err: ${stats.err}`)
-console.log(`  Сумарний час: ${Math.round(stats.totalMs / 1000)}s; середній на файл: ${stats.ok ? Math.round(stats.totalMs / stats.ok / 1000) : 0}s`)
-console.log(`  Середній det-score: ${avgScore}`)
-if (stats.errors.length) {
-  console.log('Помилки:')
-  for (const e of stats.errors) console.log(`  - ${e.path}: ${e.msg}`)
-}

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

@@ -1,95 +0,0 @@
-/**
- * Batch docgen для відсутніх файлів проєкту.
- * sym < 4 → gemma3:4b orchestrated (local)
- * sym ≥ 4 → Claude Sonnet (cloud, via generateDoc pre-routing)
- */
-import { readFileSync, mkdirSync, writeFileSync } from 'node:fs'
-import { dirname, join, resolve } from 'node:path'
-import { fileURLToPath } from 'node:url'
-import { generateDoc } from './docgen-gen.mjs'
-import { extractFacts } from './docgen-extract.mjs'
-import { execSync } from 'node:child_process'
-
-const ROOT = resolve(fileURLToPath(import.meta.url), '../../../../..')
-
-// 1. Отримати список відсутніх файлів
-const scanOut = execSync('node npm/bin/n-cursor.js docgen scan', { cwd: ROOT, encoding: 'utf8' })
-const allFiles = JSON.parse(scanOut)
-const missing = allFiles.filter(x => !x.exists)
-
-console.log(`\n📋 Файлів для генерації: ${missing.length}`)
-
-// 2. Розкласти по тирах
-const cloud = [],
-  local = []
-for (const f of missing) {
-  try {
-    const src = readFileSync(join(ROOT, f.sourcePath), 'utf8')
-    const facts = extractFacts(src, join(ROOT, f.sourcePath))
-    const sym = (facts.internalSymbols ?? []).length
-    if (sym >= 4) cloud.push({ ...f, sym })
-    else local.push({ ...f, sym })
-  } catch {
-    local.push({ ...f, sym: 0 })
-  }
-}
-
-console.log(`  Local (sym<4): ${local.length}`)
-console.log(`  Cloud (sym≥4): ${cloud.length}`)
-
-const stats = { ok: 0, err: 0, localOk: 0, cloudOk: 0, errors: [] }
-
-// 3. Cloud файли (sym≥4) — generateDoc auto-routes до Claude
-console.log('\n☁️  Cloud tier...')
-for (const f of cloud) {
-  const t0 = Date.now()
-  try {
-    const result = await generateDoc(join(ROOT, f.sourcePath), { symThreshold: 4 })
-    const docAbs = join(ROOT, f.docPath)
-    mkdirSync(dirname(docAbs), { recursive: true })
-    writeFileSync(docAbs, result.md)
-    stats.ok++
-    stats.cloudOk++
-    console.log(`  ✓ ${f.sourcePath} (sym=${f.sym}, ${Math.round((Date.now() - t0) / 1000)}s)`)
-  } catch (error) {
-    stats.err++
-    stats.errors.push(f.sourcePath)
-    console.error(`  ✗ ${f.sourcePath}: ${error.message}`)
-  }
-}
-
-// 4. Local файли (sym<4) — gemma3:4b orchestrated
-console.log('\n💻 Local tier...')
-let done = 0
-for (const f of local) {
-  done++
-  const t0 = Date.now()
-  const pct = Math.round((done / local.length) * 100)
-  process.stdout.write(`  [${done}/${local.length} ${pct}%] ${f.sourcePath} ... `)
-  try {
-    const result = await generateDoc(join(ROOT, f.sourcePath), {
-      mode: 'orchestrated',
-      symThreshold: 999 // force local
-    })
-    const docAbs = join(ROOT, f.docPath)
-    mkdirSync(dirname(docAbs), { recursive: true })
-    writeFileSync(docAbs, result.md)
-    stats.ok++
-    stats.localOk++
-    process.stdout.write(`✓ ${Math.round((Date.now() - t0) / 1000)}s score=${result.score ?? '?'}\n`)
-  } catch (error) {
-    stats.err++
-    stats.errors.push(f.sourcePath)
-    process.stdout.write(`✗ ${error.message}\n`)
-  }
-}
-
-// 5. Підсумок
-console.log(`\n${'─'.repeat(50)}`)
-console.log(`✓ OK: ${stats.ok}  ✗ Err: ${stats.err}`)
-console.log(`  💻 Local (gemma3:4b): ${stats.localOk} файлів`)
-console.log(`  ☁️  Cloud (Claude/pi): ${stats.cloudOk} файлів`)
-if (stats.errors.length > 0) {
-  console.log('Помилки:')
-  for (const e of stats.errors) console.log(`  - ${e}`)
-}

package/skills/docgen/js/docgen-compare-pi-vs-direct.mjs

@@ -1,95 +0,0 @@
-/**
- * A/B: docgen Tier 1 через pi cli (з omlx-провайдером у ~/.pi/agent/models.json)
- * vs прямий callOmlxMessages (`N_CURSOR_DOCGEN_BACKEND=omlx`).
- *
- * Однаковий 8-сет файлів, однаковий оркестратор (E1+E2+E3+E4), різний backend.
- * Пише в /tmp/docgen-compare/{pi,direct}/<idx>-<stem>.md і збирає метрики.
- *
- * Запуск: node npm/skills/docgen/js/docgen-compare-pi-vs-direct.mjs [--from N] [--limit N]
- */
-import { readFileSync, mkdirSync, writeFileSync, existsSync } from 'node:fs'
-import { join, resolve, basename } from 'node:path'
-import { fileURLToPath } from 'node:url'
-import { execSync } from 'node:child_process'
-import { env } from 'node:process'
-import { generateDoc } from './docgen-gen.mjs'
-import { extractFacts } from './docgen-extract.mjs'
-
-const ROOT = resolve(fileURLToPath(import.meta.url), '../../../../..')
-const TMP = '/tmp/docgen-compare'
-
-const args = process.argv.slice(2)
-const limitIdx = args.indexOf('--limit')
-const limit = limitIdx !== -1 ? Number(args[limitIdx + 1]) : 8
-const fromIdx = args.indexOf('--from')
-const from = fromIdx !== -1 ? Number(args[fromIdx + 1]) : 1
-
-const scanOut = execSync('node npm/bin/n-cursor.js docgen scan', { cwd: ROOT, encoding: 'utf8' })
-const all = JSON.parse(scanOut)
-
-const local = []
-for (const f of all) {
-  try {
-    const src = readFileSync(join(ROOT, f.sourcePath), 'utf8')
-    const facts = extractFacts(src, join(ROOT, f.sourcePath))
-    const sym = (facts.internalSymbols ?? []).length
-    if (sym < 4) local.push({ ...f, sym })
-  } catch {}
-}
-const slice = local.slice(from, from + limit)
-
-mkdirSync(join(TMP, 'pi'), { recursive: true })
-mkdirSync(join(TMP, 'direct'), { recursive: true })
-
-async function runBackendAsync(kind) {
-  if (kind === 'direct') env.N_CURSOR_DOCGEN_BACKEND = 'omlx'
-  else delete env.N_CURSOR_DOCGEN_BACKEND
-  const out = { ok: 0, err: 0, totalMs: 0, scores: [], lengths: [], errors: [], times: [] }
-  console.log(`\n══════ Backend: ${kind} ══════`)
-  for (let i = 0; i < slice.length; i++) {
-    const f = slice[i]
-    const t0 = Date.now()
-    const stem = basename(f.sourcePath).replace(/\.[^.]+$/, '')
-    const destFile = join(TMP, kind, `${String(i + 1).padStart(2, '0')}-${stem}.md`)
-    process.stdout.write(`  [${i + 1}/${slice.length}] sym=${f.sym} ${f.sourcePath} ... `)
-    try {
-      const r = await generateDoc(join(ROOT, f.sourcePath), { symThreshold: 999, cloudModel: null })
-      writeFileSync(destFile, r.md)
-      const ms = Date.now() - t0
-      out.ok++
-      out.totalMs += ms
-      out.times.push(ms)
-      out.scores.push(r.score ?? 0)
-      out.lengths.push(r.md.length)
-      process.stdout.write(`✓ ${Math.round(ms / 1000)}s score=${r.score ?? '?'} chars=${r.md.length}\n`)
-    } catch (error) {
-      out.err++
-      out.errors.push({ path: f.sourcePath, msg: error.message })
-      process.stdout.write(`✗ ${error.message}\n`)
-    }
-  }
-  return out
-}
-
-const direct = await runBackendAsync('direct')
-const pi = await runBackendAsync('pi')
-
-function avg(a) { return a.length ? Math.round(a.reduce((x, y) => x + y, 0) / a.length) : 0 }
-function median(a) {
-  if (!a.length) return 0
-  const s = a.toSorted((x, y) => x - y)
-  return s[Math.floor(s.length / 2)]
-}
-
-const report = {
-  files: slice.map(f => f.sourcePath),
-  direct: { ok: direct.ok, err: direct.err, avgMs: avg(direct.times), medianMs: median(direct.times), avgScore: avg(direct.scores), avgChars: avg(direct.lengths), totalSec: Math.round(direct.totalMs / 1000) },
-  pi: { ok: pi.ok, err: pi.err, avgMs: avg(pi.times), medianMs: median(pi.times), avgScore: avg(pi.scores), avgChars: avg(pi.lengths), totalSec: Math.round(pi.totalMs / 1000) }
-}
-writeFileSync(join(TMP, 'report.json'), JSON.stringify(report, null, 2))
-
-console.log(`\n${'─'.repeat(60)}\nA/B SUMMARY (${slice.length} файлів, той самий оркестратор)\n${'─'.repeat(60)}`)
-console.log(`Backend        | ok | err | avg s | median s | avg score | avg chars | total s`)
-console.log(`direct (curl)  | ${direct.ok}  | ${direct.err}   | ${Math.round(report.direct.avgMs / 1000)}    | ${Math.round(report.direct.medianMs / 1000)}        | ${report.direct.avgScore}        | ${report.direct.avgChars}      | ${report.direct.totalSec}`)
-console.log(`pi cli         | ${pi.ok}  | ${pi.err}   | ${Math.round(report.pi.avgMs / 1000)}    | ${Math.round(report.pi.medianMs / 1000)}        | ${report.pi.avgScore}        | ${report.pi.avgChars}      | ${report.pi.totalSec}`)
-console.log(`\nФайли: ${TMP}/{direct,pi}/<idx>-<stem>.md\nReport: ${TMP}/report.json`)