@nitra/cursor 12.15.0 → 12.16.0

package/lib/omlx.mjs

@@ -1,220 +0,0 @@
-/**
- * Спільний транспорт до локального omlx-сервера (OpenAI-сумісний MLX,
- * `http://localhost:8000/v1/chat/completions`). Text-only: жодних `tools`/
- * `tool_calls` — сервер їх не підтримує (див. ADR
- * `260610-1349-агентна-пастка-js-owned-loop-через-omlx-замість-pi-tool-loop`).
- *
- * Маршрутизація між omlx і pi — за конвенцією префікса в model-id:
- *   `omlx/<model>` → прямий HTTP до omlx (локальний inference, без pi)
- *   будь-що інше    → pi CLI (хмарні провайдери або pi-дефолт)
- *
- * Так `resolveModel(tier)` лишається незмінним: достатньо виставити локальний
- * тир у форматі `N_LOCAL_MIN_MODEL=omlx/mlx-community--gemma-4-e2b-it-4bit`, і
- * виклик сам піде напряму в omlx замість pi.
- *
- * Auth: якщо в omlx увімкнено API-ключ, він резолвиться через
- * `resolveOmlxApiKey` (opts → `N_CURSOR_OMLX_KEY` → `~/.omlx/settings.json`)
- * і шлеться як `Authorization: Bearer …`.
- */
-import { spawnSync } from 'node:child_process'
-import { readFileSync } from 'node:fs'
-import { homedir } from 'node:os'
-import { join } from 'node:path'
-import { env } from 'node:process'
-
-/** Дефолтний endpoint omlx (override — `N_CURSOR_OMLX_URL`). */
-export const DEFAULT_OMLX_URL = 'http://127.0.0.1:8000/v1/chat/completions'
-
-/**
- * API-ключ для omlx-сервера, коли в ньому ввімкнено auth
- * (`~/.omlx/settings.json` → `auth.skip_api_key_verification: false`).
- * Порядок: явний `apiKey` → env `N_CURSOR_OMLX_KEY` → `auth.api_key` із
- * локального `~/.omlx/settings.json` (zero-config для власної машини; читання
- * fail-safe) → `null` (заголовок не шлеться).
- * @param {string} [apiKey] явний ключ із opts виклику
- * @returns {string|null} ключ для `Authorization: Bearer …` або null
- */
-export function resolveOmlxApiKey(apiKey) {
-  if (apiKey) return apiKey
-  if (env.N_CURSOR_OMLX_KEY) return env.N_CURSOR_OMLX_KEY
-  try {
-    const settings = JSON.parse(readFileSync(join(homedir(), '.omlx', 'settings.json'), 'utf8'))
-    return settings?.auth?.api_key || null
-  } catch {
-    return null
-  }
-}
-
-const OMLX_PREFIX = 'omlx/'
-
-/** Backoff між transient-ретраями curl (мс): 2 паузи на 3 спроби. */
-const BACKOFF_MS = [2000, 8000]
-
-/**
- * Блокуюча пауза без зайнятого циклу (sync — для retry-loop у `callOmlxRaw`).
- * @param {number} ms тривалість паузи
- * @returns {void}
- */
-function sleepSync(ms) {
-  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms)
-}
-
-/**
- * Чи цей model-id адресує локальний omlx-бекенд (префікс `omlx/`).
- * @param {unknown} model перевірюваний model-id
- * @returns {boolean} true, якщо рядок починається з `omlx/`
- */
-export function isOmlxModel(model) {
-  return typeof model === 'string' && model.startsWith(OMLX_PREFIX)
-}
-
-/**
- * Прибирає `omlx/`-префікс → чистий model-id для omlx API.
- * Не-omlx-рядки повертає без змін.
- * @param {string} model model-id (можливо з префіксом)
- * @returns {string} model-id без `omlx/`
- */
-export function omlxModelId(model) {
-  return isOmlxModel(model) ? model.slice(OMLX_PREFIX.length) : model
-}
-
-const THINK_TAG_RE = /<think>([\s\S]*?)<\/think>/
-
-/**
- * Витягує reasoning (думки моделі) з omlx-`message`. Джерела за пріоритетом:
- *   - `field`     — окреме поле `message.reasoning_content` (Qwen3-Thinking тощо);
- *   - `think_tag` — `<think>…</think>` усередині `content` (інші thinking-моделі);
- *   - `truncated` — `finish_reason: "length"` зрізав думку в `content` до закриття
- *                   тега → сирий reasoning лишився в `content` без `</think>`;
- *   - `null`      — reasoning немає (не-thinking модель).
- * @param {{content?:string, reasoning_content?:string}} message обʼєкт `choices[0].message`
- * @param {string|null} finishReason `choices[0].finish_reason`
- * @returns {{ reasoning: string|null, reasoningSource: 'field'|'think_tag'|'truncated'|null }} текст думок і його джерело
- */
-export function extractReasoning(message, finishReason) {
-  const field = message?.reasoning_content
-  if (field && field.trim()) return { reasoning: field, reasoningSource: 'field' }
-  const content = message?.content ?? ''
-  const m = content.match(THINK_TAG_RE)
-  if (m) return { reasoning: m[1].trim(), reasoningSource: 'think_tag' }
-  if (finishReason === 'length' && content.trim()) return { reasoning: content, reasoningSource: 'truncated' }
-  return { reasoning: null, reasoningSource: null }
-}
-
-/**
- * Парсить успішну (curl-exit 0) omlx-відповідь у багатий обʼєкт.
- * @param {string} stdout сире тіло відповіді curl
- * @param {number} attempt номер успішної спроби (для поля `attempts`)
- * @returns {{ content:string, reasoning:string|null, reasoningSource:string|null, finishReason:string|null, usage:object|null, attempts:number }} багатий результат
- * @throws {Error} на поганому JSON, api-помилці чи порожньому контенті
- */
-function parseOmlxResponse(stdout, attempt) {
-  let j
-  try {
-    j = JSON.parse(stdout)
-  } catch {
-    throw new Error(`omlx bad json: ${stdout?.slice(0, 200) ?? ''}`)
-  }
-  if (j.error) throw new Error(`omlx api: ${JSON.stringify(j.error).slice(0, 300)}`)
-  const message = j.choices?.[0]?.message ?? {}
-  const finishReason = j.choices?.[0]?.finish_reason ?? null
-  const content = message.content?.trim() ?? ''
-  if (!content) throw new Error(`omlx empty content (finish=${finishReason})`)
-  const { reasoning, reasoningSource } = extractReasoning(message, finishReason)
-  return { content, reasoning, reasoningSource, finishReason, usage: j.usage ?? null, attempts: attempt }
-}
-
-/**
- * Ядро прямого HTTP-виклику до omlx через `curl` (spawnSync). Повертає **багатий**
- * обʼєкт: контент + reasoning + usage + finish_reason + кількість спроб. Ретраїть
- * transient-помилки (curl 18/28/52/56 + spawnSync ETIMEDOUT) із backoff 2s→8s.
- * @param {Array<{role:string, content:string}>} messages OpenAI-messages (system+user збережено)
- * @param {string} model model-id (з/без `omlx/`-префікса); порожній і без `fallbackModel` → throw
- * @param {{ url?: string, timeoutMs?: number, temperature?: number, maxTokens?: number, fallbackModel?: string, apiKey?: string, backoffMs?: number[], thinkingBudget?: number }} [opts] URL, timeout, температура, ліміт виходу, fallback-модель, API-ключ, backoff між ретраями (мс), бюджет thinking-токенів (0 = вимкнено)
- * @returns {{ content:string, reasoning:string|null, reasoningSource:string|null, finishReason:string|null, usage:object|null, attempts:number }} багатий результат виклику
- * @throws {Error} на curl-помилці, не-200 exit, поганому JSON чи порожньому контенті
- */
-export function callOmlxRaw(messages, model, opts = {}) {
-  const {
-    url = env.N_CURSOR_OMLX_URL ?? DEFAULT_OMLX_URL,
-    timeoutMs = 60_000,
-    temperature = 0.2,
-    maxTokens = 4096,
-    fallbackModel = env.N_CURSOR_OMLX_MODEL ?? '',
-    apiKey,
-    backoffMs = BACKOFF_MS,
-    thinkingBudget = 0
-  } = opts
-
-  const m = omlxModelId(model) || fallbackModel
-  if (!m) {
-    throw new Error('omlx: модель не задано — постав N_LOCAL_MIN_MODEL (або N_CURSOR_OMLX_MODEL)')
-  }
-  const body = JSON.stringify({
-    model: m,
-    messages,
-    max_tokens: maxTokens,
-    temperature,
-    ...(thinkingBudget > 0 ? { thinking_budget: thinkingBudget } : {})
-  })
-  // Ключ локального сервера в argv допустимий: localhost-секрет власної машини,
-  // короткоживучий процес; stdin уже зайнятий body (`--data-binary @-`).
-  const key = resolveOmlxApiKey(apiKey)
-  const authArgs = key ? ['-H', `Authorization: Bearer ${key}`] : []
-
-  // 18=transfer closed, 28=operation timeout, 52=empty reply, 56=recv failure — усі transient.
-  const TRANSIENT_CURL_CODES = new Set([18, 28, 52, 56])
-  let lastErr
-  for (let attempt = 1; attempt <= 3; attempt++) {
-    const r = spawnSync(
-      'curl',
-      [
-        '-sS',
-        '-X',
-        'POST',
-        url,
-        '-H',
-        'Content-Type: application/json',
-        '-H',
-        'Connection: close',
-        ...authArgs,
-        '--max-time',
-        String(Math.ceil(timeoutMs / 1000)),
-        '--data-binary',
-        '@-'
-      ],
-      { input: body, encoding: 'utf8', timeout: timeoutMs + 5000 }
-    )
-    if (r.error) {
-      lastErr = new Error(`omlx curl error: ${r.error.message}`)
-      // spawnSync-таймаут (ETIMEDOUT) — transient: сервер перевантажений, ретраїмо з backoff.
-      if (r.error.code === 'ETIMEDOUT' && attempt < 3) {
-        sleepSync(backoffMs[attempt - 1])
-        continue
-      }
-      break
-    }
-    if (r.status !== 0) {
-      if (TRANSIENT_CURL_CODES.has(r.status) && attempt < 3) {
-        lastErr = new Error(`omlx curl exit ${r.status} (transient, retry ${attempt})`)
-        sleepSync(backoffMs[attempt - 1])
-        continue
-      }
-      throw new Error(`omlx curl exit ${r.status}: ${r.stderr?.slice(0, 300) ?? ''}`)
-    }
-    return parseOmlxResponse(r.stdout, attempt)
-  }
-  throw lastErr ?? new Error('omlx unknown failure')
-}
-
-/**
- * Тонка обгортка над `callOmlxRaw` для споживачів, яким потрібен лише текст.
- * Контракт незмінний: повертає непорожній `choices[0].message.content`.
- * @param {Array<{role:string, content:string}>} messages OpenAI-messages
- * @param {string} model model-id (з/без `omlx/`-префікса)
- * @param {object} [opts] ті самі опції, що й у `callOmlxRaw`
- * @returns {string} непорожній контент відповіді
- */
-export function callOmlx(messages, model, opts = {}) {
-  return callOmlxRaw(messages, model, opts).content
-}

package/scripts/lib/fix/analyze-escalation.mjs

@@ -1,353 +0,0 @@
-/**
- * Аналітика escalation-логу (спека 2026-06-19-fix-escalation-analysis-design).
- *
- * Читає записи рунгів драбини (`escalation-log.mjs`) — за один прогін (від байтового
- * зсуву) або весь лог, — ділить на чанки за бюджетом символів і просить хмарну
- * **avg**-модель проаналізувати: як зменшити LLM-залежність fix-конформності.
- * Мета аналізу — конкретні правки пакета `@nitra/cursor`:
- *   (A) новий ДЕТЕРМІНОВАНИЙ T0-патерн (`t0.mjs`) — прибирає LLM зовсім;
- *   (B) уточнення `.mdc`-інструкцій правила, щоб локальна min-модель влучала з першого рунга;
- *   (C) зміна скрипта/чека в пакеті.
- * Результат — markdown-звіт у `.n-cursor/fix-escalation-analysis.md` (append із timestamp).
- *
- * Викликається CLI `n-cursor analyze-escalation` (весь лог) і наприкінці `lint --full`
- * (записи цього прогону). Кожен виклик моделі йде через спільний `callLlm` (wire-trace).
- */
-import { appendFileSync, mkdirSync, readFileSync, statSync } from 'node:fs'
-import { dirname, join } from 'node:path'
-import { cwd as processCwd, env } from 'node:process'
-
-import { callLlm } from '../../../lib/llm.mjs'
-import { CLOUD_AVG } from '../../../lib/models.mjs'
-import { escalationLogPath } from './escalation-log.mjs'
-
-/** Значення `N_CURSOR_FIX_ANALYZE`, що вимикають авто-аналіз наприкінці lint. */
-const KILL_VALUES = new Set(['0', 'false', 'off', 'no'])
-/** Бюджет символів на один чанк (щоб великий лог не перевищив контекст моделі). */
-const DEFAULT_CHUNK_CHARS = 40_000
-/** Timeout одного аналітичного виклику (мс) — аналіз може бути об'ємним. */
-const ANALYZE_TIMEOUT_MS = 180_000
-
-/** No-op логер за замовчуванням. */
-const NOOP_LOG = () => {
-  /* тихо */
-}
-
-/**
- * Спільна мета-інструкція для аналітичних викликів.
- */
-const GOAL = [
-  `You analyze logs from @nitra/cursor's automated rule-conformance fixer ("fix").`,
-  `Each record = one attempt by a model to fix a rule-conformance violation on a rung of`,
-  `an escalation ladder. Fields: ruleId; tier (local-min|local-min-retry|cloud-min|cloud-avg);`,
-  `model; callOk (model call+apply succeeded); recheckOk (rule PASSED after this rung — "did it help");`,
-  `callError; diagnosis (model's self-stated reason a prior attempt failed); remainingViolation.`,
-  ``,
-  `Goal: reduce LLM dependence and time-to-green. For RECURRING patterns recommend CONCRETE changes`,
-  `to the @nitra/cursor package, in priority order:`,
-  `(A) a new DETERMINISTIC T0-auto pattern for npm/scripts/lib/fix/t0.mjs — give a regex that matches`,
-  `    the violation output + the mechanical fix. PREFERRED: removes the LLM entirely.`,
-  `(B) a clarification to a rule's .mdc instructions so the LOCAL min-model succeeds on the FIRST rung.`,
-  `(C) a script/check change elsewhere in the package.`,
-  `Prioritise rules that escalated to cloud (cloud-min/cloud-avg) or failed repeatedly — they cost most.`,
-  `Ignore rules resolved at local-min with no retry — they already work.`
-].join('\n')
-
-/**
- * Чи увімкнено авто-аналіз наприкінці lint (default — так; kill-switch `N_CURSOR_FIX_ANALYZE`).
- * @returns {boolean} true, якщо аналіз дозволено
- */
-export function analysisEnabled() {
-  const v = env.N_CURSOR_FIX_ANALYZE
-  if (v === undefined) return true
-  return !KILL_VALUES.has(v.toLowerCase())
-}
-
-/**
- * Розмір escalation-логу в байтах (0, якщо файлу немає/вимкнено) — для since-offset.
- * @param {string|null} [path] шлях логу
- * @returns {number} розмір у байтах
- */
-export function escalationLogSize(path = escalationLogPath()) {
-  if (!path) return 0
-  try {
-    return statSync(path).size
-  } catch {
-    return 0
-  }
-}
-
-/**
- * Читає записи escalation-логу від байтового зсуву (default 0 — весь лог). Зсув завжди
- * на межі рядка (захоплюється після завершеного append), тож мультибайтні символи не б'ються.
- * Биті JSON-рядки пропускаються.
- * @param {string|null} path шлях логу
- * @param {number} [sinceOffset] байтовий зсув початку читання
- * @returns {object[]} розпарсені записи
- */
-export function readEscalationRecords(path, sinceOffset = 0) {
-  if (!path) return []
-  let buf
-  try {
-    buf = readFileSync(path)
-  } catch {
-    return []
-  }
-  const text = (sinceOffset > 0 ? buf.subarray(sinceOffset) : buf).toString('utf8')
-  const out = []
-  for (const line of text.split('\n')) {
-    const t = line.trim()
-    if (!t) continue
-    try {
-      out.push(JSON.parse(t))
-    } catch {
-      /* битий рядок — пропускаємо */
-    }
-  }
-  return out
-}
-
-/** Маркер skip-запису avg-рунга (кеп вичерпано) — НЕ фактичний виклик моделі. */
-const AVG_SKIP_MARKER = 'cloud-avg cap reached'
-
-/**
- * Рахує фактичні виклики моделей за тирами (skip-записи avg-кепу не рахуються).
- * @param {object[]} records записи рунгів
- * @returns {{ local: number, cloudMin: number, cloudAvg: number }} лічильники викликів
- */
-export function summarizeCalls(records) {
-  const stats = { local: 0, cloudMin: 0, cloudAvg: 0 }
-  for (const r of records) {
-    if (r.callError === AVG_SKIP_MARKER) continue
-    if (r.tier === 'cloud-avg') stats.cloudAvg++
-    else if (r.tier === 'cloud-min') stats.cloudMin++
-    else if (typeof r.tier === 'string' && r.tier.startsWith('local')) stats.local++
-  }
-  return stats
-}
-
-/**
- * Друкує резюме викликів моделей за цей прогін (локальна / cloud-min / cloud-avg).
- * No-op, якщо викликів не було. Читає записи від `sinceOffset`.
- * @param {number} sinceOffset байтовий зсув логу перед прогоном
- * @param {(s: string) => void} log логер
- * @returns {void}
- */
-export function reportRunStats(sinceOffset, log) {
-  const { local, cloudMin, cloudAvg } = summarizeCalls(readEscalationRecords(escalationLogPath(), sinceOffset))
-  if (local + cloudMin + cloudAvg === 0) return
-  log(
-    `\n📊 LLM-виклики fix-конформності (цей прогін): ` +
-      `локальна ${local} · cloud-min ${cloudMin} · cloud-avg ${cloudAvg}\n`
-  )
-}
-
-/**
- * Стискає запис до полів, важливих для аналізу (без ts/ms-шуму).
- * @param {object} r сирий запис рунга
- * @returns {object} компактний запис
- */
-function summarizeRecord(r) {
-  return {
-    ruleId: r.ruleId,
-    tier: r.tier,
-    model: r.model,
-    callOk: r.callOk,
-    recheckOk: r.recheckOk,
-    callError: r.callError ?? null,
-    diagnosis: r.diagnosis ?? null,
-    remainingViolation: r.remainingViolation ?? null
-  }
-}
-
-/**
- * Ділить записи на чанки так, щоб JSON кожного чанка не перевищував `maxChars`.
- * Працює на стиснених записах (саме вони йдуть у prompt).
- * @param {object[]} records сирі записи
- * @param {number} [maxChars] бюджет символів на чанк
- * @returns {object[][]} чанки стиснених записів
- */
-export function chunkRecords(records, maxChars = DEFAULT_CHUNK_CHARS) {
-  const items = records.map(r => summarizeRecord(r))
-  const chunks = []
-  let cur = []
-  let size = 0
-  for (const it of items) {
-    const len = JSON.stringify(it).length + 1
-    if (cur.length > 0 && size + len > maxChars) {
-      chunks.push(cur)
-      cur = []
-      size = 0
-    }
-    cur.push(it)
-    size += len
-  }
-  if (cur.length > 0) chunks.push(cur)
-  return chunks
-}
-
-/**
- * Prompt для аналізу одного чанка.
- * @param {object[]} items стиснені записи чанка
- * @param {number} idx індекс чанка (0-based)
- * @param {number} total всього чанків
- * @returns {string} текст prompt
- */
-function buildChunkPrompt(items, idx, total) {
-  return [
-    GOAL,
-    ``,
-    `Log chunk ${idx + 1}/${total} (${items.length} records):`,
-    JSON.stringify(items),
-    ``,
-    `Return concise markdown: per recommendation — target ruleId, type (A/B/C), and the concrete change`,
-    `(for A: the regex + mechanical fix; for B: the exact .mdc clarification; for C: the script change).`
-  ].join('\n')
-}
-
-/**
- * Prompt для злиття часткових аналізів у фінальний звіт.
- * @param {string[]} partials часткові аналізи чанків
- * @returns {string} текст prompt
- */
-function buildSynthesisPrompt(partials) {
-  return [
-    GOAL,
-    ``,
-    `Below are partial analyses of separate log chunks. Merge, dedupe and prioritise into ONE report.`,
-    ``,
-    partials.map((p, i) => `--- chunk ${i + 1} ---\n${p}`).join('\n\n'),
-    ``,
-    `Return the final markdown report: recommendations ordered highest-impact first.`
-  ].join('\n')
-}
-
-/**
- * Безпечний виклик моделі: ковтає помилку у `null` (аналіз не має валити lint).
- * @param {(messages: object[], model: string, opts: object) => string} call функція callLlm
- * @param {string} prompt текст prompt
- * @param {string} model model-id
- * @returns {string|null} текст відповіді або null
- */
-function safeCall(call, prompt, model) {
-  try {
-    const text = call([{ role: 'user', content: prompt }], model, {
-      timeoutMs: ANALYZE_TIMEOUT_MS,
-      caller: 'fix-analyze'
-    })
-    return text || null
-  } catch {
-    return null
-  }
-}
-
-/**
- * Аналізує записи: чанкінг → виклик avg-моделі по чанках → синтез (якщо чанків >1).
- * Синхронний (callLlm — spawnSync-based).
- * @param {object[]} records записи escalation-логу
- * @param {{ model?: string, callLlm?: (messages: object[], model: string, opts: object) => string, log?: (s: string) => void, maxChars?: number }} [opts]
- *   `model` — модель (default `CLOUD_AVG`); `callLlm` — інжекція для тестів; `log` — логер
- * @returns {{ report: string|null, chunks: number, reason: string }} звіт і метадані
- */
-export function analyzeEscalations(records, opts = {}) {
-  const model = opts.model ?? CLOUD_AVG
-  const call = opts.callLlm ?? callLlm
-  const log = opts.log ?? NOOP_LOG
-  const maxChars = opts.maxChars ?? DEFAULT_CHUNK_CHARS
-
-  if (records.length === 0) return { report: null, chunks: 0, reason: 'no-records' }
-  if (!model) return { report: null, chunks: 0, reason: 'no-cloud-avg-model' }
-
-  const chunks = chunkRecords(records, maxChars)
-  const partials = []
-  for (const [i, chunk] of chunks.entries()) {
-    log(`  🔎 escalation-analysis: чанк ${i + 1}/${chunks.length} (${chunk.length} записів)`)
-    const text = safeCall(call, buildChunkPrompt(chunk, i, chunks.length), model)
-    if (text) partials.push(text)
-  }
-
-  if (partials.length === 0) return { report: null, chunks: chunks.length, reason: 'empty-responses' }
-  const report = partials.length === 1 ? partials[0] : safeCall(call, buildSynthesisPrompt(partials), model)
-  return { report, chunks: chunks.length, reason: report ? 'ok' : 'empty-responses' }
-}
-
-/**
- * Шлях markdown-звіту аналізу.
- * @param {string} [cwd] корінь
- * @returns {string} шлях .n-cursor/fix-escalation-analysis.md
- */
-export function analysisReportPath(cwd = processCwd()) {
-  return join(cwd, '.n-cursor', 'fix-escalation-analysis.md')
-}
-
-/**
- * Дописує звіт у markdown-файл із timestamp-заголовком.
- * @param {string} report текст звіту
- * @param {string} cwd корінь
- * @param {string} ts ISO-час
- * @returns {string} шлях файлу
- */
-export function writeAnalysisReport(report, cwd, ts) {
-  const path = analysisReportPath(cwd)
-  mkdirSync(dirname(path), { recursive: true })
-  appendFileSync(path, `\n## Аналіз ${ts}\n\n${report}\n`, 'utf8')
-  return path
-}
-
-/**
- * Спільний шлях: аналіз записів → запис звіту → лог-підсумок.
- * @param {object[]} records записи
- * @param {string} cwd корінь
- * @param {(s: string) => void} log логер
- * @returns {number} 0 — ок/пропуск, 1 — модель не дала звіт
- */
-function analyzeAndReport(records, cwd, log) {
-  const res = analyzeEscalations(records, { log })
-  if (res.reason === 'no-records') {
-    log('ℹ️  escalation-analysis: немає записів для аналізу.')
-    return 0
-  }
-  if (res.reason === 'no-cloud-avg-model') {
-    log('⚠️  escalation-analysis: N_CLOUD_AVG_MODEL не заданий — аналіз пропущено.')
-    return 0
-  }
-  if (!res.report) {
-    log('⚠️  escalation-analysis: модель не повернула звіт.')
-    return 1
-  }
-  const reportPath = writeAnalysisReport(res.report, cwd, new Date().toISOString())
-  log(`📝 escalation-analysis: звіт → ${reportPath} (${res.chunks} чанк(и))`)
-  return 0
-}
-
-/**
- * CLI `n-cursor analyze-escalation` — аналізує ВЕСЬ escalation-лог і пише звіт.
- * @param {string[]} _args аргументи (зарезервовано)
- * @param {string} [cwd] корінь
- * @returns {number} exit code
- */
-export function runEscalationAnalysisCli(_args, cwd = processCwd()) {
-  const records = readEscalationRecords(escalationLogPath(), 0)
-  return analyzeAndReport(records, cwd, s => console.log(s))
-}
-
-/**
- * Хук наприкінці `lint --full` (non-read-only): аналізує записи ЦЬОГО прогону
- * (від `sinceOffset`). Gated: kill-switch, наявність cloud-avg, наявність записів.
- * Помилки не валять lint.
- * @param {string} cwd корінь
- * @param {number} sinceOffset байтовий зсув логу перед прогоном
- * @param {(s: string) => void} log логер
- * @returns {void}
- */
-export function maybeAnalyzeEscalation(cwd, sinceOffset, log) {
-  if (!analysisEnabled()) return
-  const records = readEscalationRecords(escalationLogPath(), sinceOffset)
-  if (records.length === 0) return
-  if (!CLOUD_AVG) {
-    log('\nℹ️  escalation-analysis: були LLM-ескалації, але N_CLOUD_AVG_MODEL не заданий — аналіз пропущено.\n')
-    return
-  }
-  log('\n🔬 escalation-analysis: аналізую ескалації цього прогону…\n')
-  analyzeAndReport(records, cwd, log)
-}

package/scripts/lib/fix/docs/analyze-escalation.md

@@ -1,44 +0,0 @@
----
-type: JS Module
-title: analyze-escalation.mjs
-resource: npm/scripts/lib/fix/analyze-escalation.mjs
-docgen:
-  crc: f26cd4c7
-  model: omlx/gemma-4-e4b-it-OptiQ-4bit
-  score: 100
----
-
-Аналізує записи рунгів драбини з `escalation-log.mjs` для виявлення шляхів зменшення LLM-залежності у fix-конформності. Лог обробляється за один прогін (від байтового зсуву) або повністю, ділячись на чанки для аналізу хмарною **avg**-моделлю. Мета аналізу — визначити конкретні правки пакета `@nitra/cursor`: (A) новий ДЕТЕРМІНОВАНИЙ T0-патерн (`t0.mjs`), (B) уточнення `.mdc`-інструкцій правила, або (C) зміна скрипта/чека. Результат зберігається у markdown-звіт `.n-cursor/fix-escalation-analysis.md` (append із timestamp) після виклику CLI `n-cursor analyze-escalation`.
-
-## Поведінка
-
-analysisEnabled визначає, чи дозволено виконувати автоматичний аналіз ескалації наприкінці процесу `lint`.
-escalationLogSize повертає розмір файлу логу ескалації у байтах.
-readEscalationRecords читає записи логу ескалації, починаючи з заданого байтового зсуву, та повертає їх як масив об'єктів.
-summarizeCalls рахує кількість викликів моделей для різних рівнів (локальний, cloud-min, cloud-avg) у наданих записах.
-reportRunStats друкує резюме кількості викликів моделей для поточного прогону, використовуючи заданий байтовий зсув.
-chunkRecords ділить масив стиснених записів на менші чанки, щоб кожен чанк не перевищив заданий бюджет символів.
-analyzeEscalations аналізує надані записи, ділить їх на чанки, викликає модель для аналізу кожного чанка, а потім синтезує фінальний звіт.
-analysisReportPath повертає шлях до файлу, де зберігається звіт аналізу ескалації.
-writeAnalysisReport дописує згенерований звіт у markdown-файл у відповідному шляху, додаючи до нього мітку часу.
-runEscalationAnalysisCli виконує повний аналіз всього логу ескалації та записує звіт.
-maybeAnalyzeEscalation виконує аналіз ескалацій лише для записів поточного прогону, якщо дозволено та є необхідні умови.
-
-## Публічний API
-
-analysisEnabled — Вмикає автоматичний аналіз після завершення lint.
-escalationLogSize — Визначає максимальний розмір escalation-логу в байтах.
-readEscalationRecords — Зчитує записи з логу, починаючи з заданого байтового зсуву.
-summarizeCalls — Підраховує реальні виклики моделей за тирами, ігноруючи записи про середнє кешування.
-reportRunStats — Виводить підсумок викликів моделей за поточний запуск.
-chunkRecords — Розбиває записи на менші частини, щоб розмір JSON кожного чанку не перевищував заданий ліміт.
-analyzeEscalations — Обробляє записи: розбиває їх на чанки, викликає модель для кожного чанку та синтезує результат, якщо чанків більше одного.
-analysisReportPath — Вказує шлях для збереження markdown-звіту аналізу.
-writeAnalysisReport — Додає звіт до markdown-файлу, додаючи до нього мітку часу.
-runEscalationAnalysisCli — Виконує повний аналіз всього логу escalation через інтерфейс командного рядка.
-maybeAnalyzeEscalation — Запускає аналіз записів поточного прогону після `lint --full`, якщо це дозволено налаштуваннями.
-
-## Гарантії поведінки
-
-- Перехоплює помилки і не пропускає винятків назовні (fail-safe).
-- За певних помилок повертає порожнє значення (напр. `null`) замість винятку.

package/scripts/lib/fix/docs/llm-fix-apply.md

@@ -1,31 +0,0 @@
----
-type: JS Module
-title: llm-fix-apply.mjs
-resource: npm/scripts/lib/fix/llm-fix-apply.mjs
-docgen:
-  crc: 49f989ca
-  model: omlx/gemma-4-e4b-it-OptiQ-4bit
-  score: 100
----
-
-## Огляд
-
-Це спільне ядро LLM-фіксу, призначене для оркестрації процесу застосування змін, згенерованих моделлю. Модуль використовує `llm-worker.mjs` та `llm-lint-fix.mjs` для забезпечення конформності та виконання лінтер-фіксів. Основний функціонал включає: парсинг відповіді LLM за схемою `{changes:[{path,content}]}` (через `parseChangesResponse`), зчитування необхідних файлів (`readFilesForFix`), та безпечне застосування змін (`applyChanges`). Система реалізує механізм fail-safe, перехоплюючи помилки та повертаючи `null` замість винятків для певних сценаріїв. При цьому шляхи `.git` та `node_modules` свідомо ігноруються.
-
-## Поведінка
-
-parseChangesResponse парсить сирий текст відповіді моделі, витягуючи структуру змін у форматі патчу, або повертає null, якщо парсинг неможливий.
-readFilesForFix читає вміст файлів, вказаних у списку, відносно кореня проєкту. Якщо прямий шлях не знайдено, шукає файл за його базовим ім'ям у проєкті, ігноруючи каталоги `.git` та `node_modules`.
-applyChanges записує вміст, наданий у змінних, у відповідні файли проєкту, створюючи необхідні каталоги, якщо вони відсутні.
-
-## Публічний API
-
-parseChangesResponse — розбирає JSON-відповідь моделі, витягуючи вміст першого об'єкта.
-readFilesForFix — зчитує вміст файлів за заданими шляхами, шукаючи їх у системі, якщо прямий шлях не знайдено.
-applyChanges — замінює вміст файлів на новий, наданий у змінній `changes`.
-
-## Гарантії поведінки
-
-- Перехоплює помилки і не пропускає винятків назовні (fail-safe).
-- За певних помилок повертає порожнє значення (напр. `null`) замість винятку.
-- Свідомо пропускає шляхи: `.git`, `node_modules`.