@nitra/cursor 12.14.0 → 12.15.1

package/scripts/lib/fix/docs/orchestrator.md

@@ -3,29 +3,38 @@ type: JS Module
 title: orchestrator.mjs
 resource: npm/scripts/lib/fix/orchestrator.mjs
 docgen:
-  crc: c34d0630
+  crc: c6f15470
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 100
 ---
 
-Модуль відповідає за управління процесом вирішення порушень. Він будує послідовність тирів ескалації за допомогою `buildLadder`. Функція `parseOrchestratorArgs` визначає бюджет LLM та фільтр правил. Далі, `runOrchestratorCli` виконує процес виправлення правил, послідовно застосовуючи `escalateRule` по тирах до досягнення першого успішного вирішення.
+## Огляд
+
+Модуль відповідає за оркестрацію вирішення порушень. Він парсить аргументи для визначення бюджету та фільтрів за допомогою `parseOrchestratorArgs`. Потім він будує послідовність тирів ескалації, використовуючи `buildLadder`, і може ескалувати правила за допомогою `escalateRule`. Нарешті, він виконує повний цикл фіксації порушень через `runOrchestratorCli`.
 
 ## Поведінка
 
-buildLadder будує послідовність тирів ескалації для вирішення порушень.
-escalateRule проходить по послідовності тирів, намагаючись вирішити одне правило до першого успішного перевірки.
-parseOrchestratorArgs парсить аргументи командного рядка для визначення максимального бюджету LLM та фільтра правил.
-runOrchestratorCli виконує повний процес виправлення правил, використовуючи послідовність тирів та бюджет LLM.
+buildLadder будує послідовність тирів ескалації для вирішення порушень, від локальних до хмарних моделей.
+escalateRule проводить один прогін по послідовності тирів, намагаючись вирішити порушення, і повертає статус вирішення та використаний бюджет хмарних викликів.
+parseOrchestratorArgs парсить аргументи командного рядка, щоб визначити максимальний бюджет хмарних викликів та фільтр правил.
+runOrchestratorCli виконує повний цикл фіксації порушень: початкова перевірка, детермінований фікс T0-auto, ітеративний LLM-фікс за драбиною ескалації, а потім фінальна перевірка.
 
 ## Публічний API
 
-buildLadder — Створює послідовність моделей для ескалації, виходячи з доступних рівнів. Недоступні рівні ігноруються.
+buildLadder — Створює послідовність моделей для ескалації, виходячи з доступних рівнів.
+
+local-min — Перший прохід з локальною мінімальною моделлю.
+local-min-retry — Повторний прохід локальною моделлю з урахуванням результатів попереднього кроку.
+cloud-min — Використання мінімальної хмарної моделі з зворотним зв'язком.
+cloud-avg — Використання середньої хмарної моделі з зворотним зв'язком, обмежене середнім бюджетом.
 
-escalateRule — Виконує один етап перевірки за драбиною ескалації. Для кожного кроку викликається модель, відбувається повторна перевірка правила, і результат фіксується в лозі. Процес може зупинитися достроково при певних умовах або після вичерпання ліміту.
+escalateRule — Застосовує одне правило по послідовності ескалації до першого успішного перевірки.
+Кожен рунг — Викликає обробника з попереднім результатом, перевіряє правило, фіксує результат у лозі.
+Достроковий вихід — Зупиняє процес при певних умовах (відсутність ключа, пропуск моделі на системному рівні) або перевищенні середнього бюджету.
 
-parseOrchestratorArgs — Витягує максимальне значення для середнього бюджету з аргументів командного рядка та збирає список фільтрів правил.
+parseOrchestratorArgs — Витягує максимальне значення середнього бюджету з аргументів командного рядка та збирає фільтри правил.
 
-runOrchestratorCli — Запускає основний процес оркестрації, обробляючи аргументи та керуючи виконанням правил.
+runOrchestratorCli — Запускає основний процес оркестрації з командного рядка.
 
 ## Гарантії поведінки
 

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/root-notice.mjs

@@ -5,8 +5,8 @@
  *
  * Worktree-скіли (`worktree: true`) свій root-assert уже мають у worktree-блоці
  * (`worktree-notice.mjs`): корінь worktree = його toplevel. Цей модуль — для
- * не-worktree-кейсу (напр. `n-start-check`, що прогоняє `start` усіх воркспейсів
- * у місці й має стартувати з кореня монорепо).
+ * не-worktree-кейсу (напр. `n-taze`, що мутує `package.json` безпосередньо
+ * й має стартувати з кореня монорепо).
  *
  * Блок — інструкція агенту, що читає `SKILL.md`; вставляється між стабільними
  * маркерами, ре-синк ідемпотентний: наявний блок замінюється, при `false` —

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/lib/skill-meta.mjs

@@ -7,7 +7,7 @@
  *  - `requireRoot` — boolean, опційне: чи скіл вимагає запуску з кореня репо.
  *    Worktree-скіли (`worktree:true`) вимагають кореня неявно (корінь worktree =
  *    його toplevel), тож для них поле зайве. Явний `requireRoot:true` — для
- *    in-place скілів, що мутують CWD без worktree-ізоляції (напр. `n-start-check`).
+ *    in-place скілів, що мутують CWD без worktree-ізоляції (напр. `n-taze`).
  *
  * Цим хелпером користуються `auto-skills.mjs` (автоактивація), `n-cursor.js`
  * (sync + вшивання worktree/root-блоку) і check-концерн `npm-module/js/skill_meta.mjs`,

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`.