@nitra/cursor 12.15.0 → 12.15.1

package/scripts/lib/fix/llm-worker.mjs

@@ -47,54 +47,71 @@ function extractFailPaths(output) {
 }
 
 /**
- * Для правил з `policy/<concern>/` підбирає лише ті concern-.mdc, що відповідають
- * файлам з ❌-рядків violation output. Читає безпосередньо з пакету (`PACKAGE_RULES_DIR`),
- * тому не потребує pre-generation. Fallback — null (→ повний n-{id}.mdc у caller).
+ * Збирає .mdc-контекст правила з двох джерел у пакеті (`PACKAGE_RULES_DIR`):
+ *   - `js/<check>.mdc`      — описи check-логіки (завжди всі, відсортовані за іменем);
+ *   - `policy/<c>/<c>.mdc` — concern-специфічний контент: вибираємо лише ті concern/.mdc,
+ *                         чий `target.json → files.single` збігається з failing paths
+ *                         у violation output; якщо жоден не збігається — включаємо всі.
  * @param {string} ruleId ID правила
  * @param {string} violationOutput violation output
- * @returns {string|null} конкатенація релевантних .mdc або null
+ * @returns {string|null} конкатенація зібраних .mdc або null, якщо нічого не знайдено
  */
-function selectSubCheckMdc(ruleId, violationOutput) {
-  const policyDir = join(PACKAGE_RULES_DIR, ruleId, 'policy')
-  if (!existsSync(policyDir)) return null
-
-  const failPaths = extractFailPaths(violationOutput)
-  if (failPaths.length === 0) return null
-
-  const matched = []
-  let concerns
-  try {
-    concerns = readdirSync(policyDir, { withFileTypes: true })
-  } catch {
-    return null
+function readRuleMdc(ruleId, violationOutput) {
+  const ruleDir = join(PACKAGE_RULES_DIR, ruleId)
+  const parts = []
+
+  // 1. js/**/*.mdc — завжди всі
+  const jsDir = join(ruleDir, 'js')
+  if (existsSync(jsDir)) {
+    let jsFiles
+    try {
+      jsFiles = readdirSync(jsDir)
+        .filter(f => f.endsWith('.mdc'))
+        .sort()
+    } catch {
+      jsFiles = []
+    }
+    for (const f of jsFiles) parts.push(readFileSync(join(jsDir, f), 'utf8').trim())
   }
 
-  for (const entry of concerns) {
-    if (!entry.isDirectory()) continue
-    const concernDir = join(policyDir, entry.name)
-    const targetPath = join(concernDir, 'target.json')
-    if (!existsSync(targetPath)) continue
-
-    let target
+  // 2. policy/**/*.mdc — matched через target.json; fallback — всі
+  const policyDir = join(ruleDir, 'policy')
+  if (existsSync(policyDir)) {
+    const failPaths = extractFailPaths(violationOutput)
+    let concerns
     try {
-      target = JSON.parse(readFileSync(targetPath, 'utf8'))
+      concerns = readdirSync(policyDir, { withFileTypes: true })
     } catch {
-      continue
+      concerns = []
     }
 
-    const targetFile = target?.files?.single
-    if (!targetFile) continue // walkGlob та інші типи → skip, fallback на main.mdc
-
-    // Перевіряємо чи хоч один failing path закінчується на targetFile
-    const hit = failPaths.some(p => p === targetFile || p.endsWith(`/${targetFile}`))
-    if (!hit) continue
+    const all = []
+    const matched = []
+    for (const entry of concerns) {
+      if (!entry.isDirectory()) continue
+      const concernDir = join(policyDir, entry.name)
+      const mdcEntry = readdirSync(concernDir).find(f => f.endsWith('.mdc'))
+      if (!mdcEntry) continue
+      const content = readFileSync(join(concernDir, mdcEntry), 'utf8').trim()
+      all.push(content)
+
+      const targetPath = join(concernDir, 'target.json')
+      if (!existsSync(targetPath)) continue
+      let target
+      try {
+        target = JSON.parse(readFileSync(targetPath, 'utf8'))
+      } catch {
+        continue
+      }
+      const targetFile = target?.files?.single
+      if (!targetFile) continue
+      if (failPaths.some(p => p === targetFile || p.endsWith(`/${targetFile}`))) matched.push(content)
+    }
 
-    const mdcEntry = readdirSync(concernDir).find(f => f.endsWith('.mdc'))
-    if (!mdcEntry) continue
-    matched.push(readFileSync(join(concernDir, mdcEntry), 'utf8').trim())
+    parts.push(...(matched.length > 0 ? matched : all))
   }
 
-  return matched.length > 0 ? matched.join('\n\n') : null
+  return parts.length > 0 ? parts.join('\n\n') : null
 }
 
 /**
@@ -252,7 +269,8 @@ function callModel(prompt, model, caller, timeoutMs, thinkingBudget) {
  *   `model` — перевизначення моделі; `feedback` — контекст попереднього рунга
  *   драбини (retry-with-feedback); `caller` — мітка для wire-trace; `timeoutMs` —
  *   per-tier ліміт виклику (драбина: локалі fail-fast, хмара повний);
- *   `thinkingBudget` — кількість thinking-токенів для omlx (дефолт `DEFAULT_THINKING_BUDGET`)
+ *   `thinkingBudget` — кількість thinking-токенів для omlx (дефолт `DEFAULT_THINKING_BUDGET`).
+ *   `timeoutMs` — per-tier ліміт: локальні 300s (4b повільна, backstop — turn-ceiling), хмарні 120s.
  * @returns {{ ok: boolean, error?: string, changes: Array<{path:string}>, diagnosis: string|null, reasoning: string|null, reasoningSource: string|null, promptSummary: object }}
  */
 export function runLlmWorker(ruleId, violationOutput, projectRoot, opts = {}) {
@@ -262,11 +280,8 @@ export function runLlmWorker(ruleId, violationOutput, projectRoot, opts = {}) {
   const timeoutMs = opts.timeoutMs
   const thinkingBudget = opts.thinkingBudget ?? DEFAULT_THINKING_BUDGET
 
-  // 1. Читаємо rule .mdc: спробуємо sub-check mdc для конкретної перевірки,
-  //    якщо не вдалося — fallback на повний n-{id}.mdc.
-  const subMdc = selectSubCheckMdc(ruleId, violationOutput)
-  const mdcPath = join(projectRoot, '.cursor', 'rules', `n-${ruleId}.mdc`)
-  const ruleMdc = subMdc ?? (existsSync(mdcPath) ? readFileSync(mdcPath, 'utf8') : '(rule file not found)')
+  // 1. Читаємо rule .mdc з джерела пакету: js/**/*.mdc + policy/**/*.mdc.
+  const ruleMdc = readRuleMdc(ruleId, violationOutput) ?? '(rule file not found)'
 
   // 2. Витягуємо файли з violation output і читаємо їх
   const files = readFilesForFix(extractFilePaths(violationOutput), projectRoot)
@@ -274,7 +289,6 @@ export function runLlmWorker(ruleId, violationOutput, projectRoot, opts = {}) {
   // 3. Будуємо summary промпту (для verbose-блоку) до виклику моделі
   const promptSummary = {
     ruleMdcLen: ruleMdc.length,
-    subCheckMdc: !!subMdc,
     violationLen: violationOutput.length,
     filesCount: files.length,
     filesTotalBytes: files.reduce((s, f) => s + f.content.length, 0),

package/scripts/lib/fix/orchestrator.mjs

@@ -16,11 +16,12 @@ import { CLOUD_AVG, CLOUD_MIN, LOCAL_MIN } from '../../../lib/models.mjs'
 const DEFAULT_MAX_AVG = 3
 
 /**
- * Timeout одного LLM-виклику за тиром. Локальні рунги **fail-fast**: не палити
- * стіну 120s на повільному 4b (curl exit 28) — швидше абортнути й ескалувати.
- * Хмарні — повний. Перевизначення: `N_LOCAL_FIX_TIMEOUT_MS` / `N_CLOUD_FIX_TIMEOUT_MS`.
+ * Timeout одного LLM-виклику (або всієї агентної сесії) за тиром.
+ * Локальні рунги — 5 хвилин: 4b модель повільна, основний backstop — turn-ceiling (~50).
+ * Хмарні — 2 хвилини: API-виклик швидкий, перевищення = transport-помилка.
+ * Перевизначення: `N_LOCAL_FIX_TIMEOUT_MS` / `N_CLOUD_FIX_TIMEOUT_MS`.
  */
-const LOCAL_TIMEOUT_MS = Number(env.N_LOCAL_FIX_TIMEOUT_MS) || 45_000
+const LOCAL_TIMEOUT_MS = Number(env.N_LOCAL_FIX_TIMEOUT_MS) || 300_000
 const CLOUD_TIMEOUT_MS = Number(env.N_CLOUD_FIX_TIMEOUT_MS) || 120_000
 
 /** Маркер дружнього повідомлення про відсутній API-ключ (з `llm-worker.callModel`). */

package/scripts/lib/run-lint.mjs

@@ -166,22 +166,14 @@ async function runPerFileRules(ids, ctx) {
 }
 
 /**
- * Конформність-фаза `--full` (поглинула `fix`): escalation-аналітику обрамляє зсувом логу
- * (записи саме цього прогону), у fix-режимі по конформності викликає аналіз.
+ * Конформність-фаза `--full`.
  * @param {string} cwd корінь
  * @param {boolean} readOnly лише детект
  * @param {(s: string) => void} log логер
  * @returns {Promise<number>} код конформності
  */
 async function runFullConformancePhase(cwd, readOnly, log) {
-  const { escalationLogSize, maybeAnalyzeEscalation, reportRunStats } = await import('./fix/analyze-escalation.mjs')
-  const escOffset = readOnly ? 0 : escalationLogSize()
-  const conformanceCode = await runConformance(cwd, readOnly, log)
-  if (!readOnly) {
-    reportRunStats(escOffset, log) // резюме викликів моделей (локальна / cloud-min / cloud-avg)
-    maybeAnalyzeEscalation(cwd, escOffset, log)
-  }
-  return conformanceCode
+  return runConformance(cwd, readOnly, log)
 }
 
 /**

package/scripts/utils/docs/walkDir.md

@@ -3,34 +3,31 @@ type: JS Module
 title: walkDir.mjs
 resource: npm/scripts/utils/walkDir.mjs
 docgen:
-  crc: 5e5fec27
+  crc: 73503ca2
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
 ---
 
-Файл `n-cursor.js` забезпечує рекурсивний обхід каталогів для скриптів перевірки, дозволяючи виконувати callback-функцію для кожного звичайного файлу. Він обходить дерево каталогів від заданого кореня, ігноруючи певні директорії (наприклад, `.git`, `node_modules`) та шляхи, вказані в `ignorePaths`. Це дозволяє автоматизувати процес аналізу конфігураційних файлів та інших ресурсів у проєкті.
+## Огляд
+
+Публічна функція `walkDir` здійснює рекурсивний пошук файлів у вказаному каталозі. Вона обходить файлову систему, ігноруючи каталоги `.git` та `node_modules`. Знаходячи кожен файл, вона передає його повний шлях у колбек для подальшої обробки. Компонент є read-only, тобто не виконує записів у файлову систему чи бази даних. При роботі з файловою системою він перехоплює помилки, забезпечуючи безпечну роботу без викидання винятків.
 
 ## Поведінка
 
-1.  Починається з заданого кореневого каталогу.
-2.  Для кожного підкаталогу в кореневому каталозі:
-    2.1. Перевіряє, чи є підкаталог у списку `ignorePaths`. Якщо так, пропускає обхід цього підкаталогу та його вмісту.
-    2.2. Якщо підкаталог не в списку `ignorePaths`, обробляє вміст підкаталогу:
-    2.2.1. Для кожного файлу в підкаталозі, викликає функцію `onFile` з шляхом до файлу.
-    2.2.2. Для кожного підкаталогу в підкаталозі, рекурсивно викликає функцію `walkDir` для обходу цього підкаталогу. Під час рекурсивного виклику, також перевіряє, чи є підкаталог у списку `ignorePaths`.
-3.  Не обробляє каталоги `node_modules`, `.git`, `dist`, `coverage`, `.turbo` та `.next`.
-4.  Якщо при спробі `readdir` для каталогу виникає помилка, обхід цього каталогу припиняється.
-5.  Обхід завершується, коли всі підкаталоги та файли в заданому дереві були оброблені.
+1. Викликається функція walkDir для початку рекурсивного обходу каталогу.
+2. Система розшифровує вхідний шлях до кореня обходу.
+3. Система формує додаткові правила ігнорування на основі наданих шляхів.
+4. Система завжди ігнорує каталоги .git та node_modules.
+5. Система виконує пошук усіх файлів у каталозі, застосовуючи правила ігнорування, включаючи ті, що визначені в .gitignore.
+6. У разі виникнення помилки під час пошуку, процес обходу припиняється без генерації винятку.
+7. Для кожного знайденого файлу система викликає наданий колбек, передаючи йому повний абсолютний шлях до цього файлу.
 
 ## Публічний API
 
-- walkDir — Обходить каталог рекурсивно, ігноруючи вказані шляхи.
+walkDir — рекурсивно переглядає файли та папки, ігноруючи ті, що вказані у файлі `.gitignore`.
 
 ## Гарантії поведінки
 
-- Функція рекурсивно обходить дерево каталогів, починаючи з заданого кореня.
-- Для кожного звичайного файлу викликається переданий callback.
-- Не обходить каталоги `node_modules`, `.git`, `dist`, `coverage`, `.turbo`, `.next`.
-- Може пропустити каталоги, вказані в `ignorePaths`.
-- У разі невдачі `readdir` для каталогу, функція тихо виходить без викидання помилок.
-- Функція не викидає винятки назовні.
-- У разі невдачі повертає `false` або `null`.
-- Не використовує кешування.
+- Read-only: не виконує операцій запису (ФС/БД).
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).
+- Свідомо пропускає шляхи: `.git`, `node_modules`.

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`) замість винятку.