@nitra/cursor 5.2.0 → 5.3.0

package/skills/doc-files/js/docgen-gen.mjs

@@ -7,11 +7,12 @@ import { DEFAULT_OMLX_MODEL } from '../../../lib/omlx.mjs'
 import { callLlm } from '../../../lib/llm.mjs'
 import { isRunAsCli } from '../../../scripts/cli-entry.mjs'
 import { extractFacts } from './docgen-extract.mjs'
-import { extractAnchors } from './docgen-extract-anchors.mjs'
+import { extractAnchors, anchorTokens } from './docgen-extract-anchors.mjs'
 import { QUALITY_THRESHOLD } from './docgen-crc.mjs'
 import {
   oneShotMessages,
   sectionMessages,
+  overviewMessages,
   criticMessages,
   refineMessages,
   guaranteesFromMarkers
@@ -25,6 +26,15 @@ const SECTION_KEY_CLEAN_RE = /[^а-яіїєґa-z0-9]/gi
 const CACHE_MENTION_RE = /кеш/i
 const CACHE_NEGATION_RE = /(?:не|без)\s+(?:\S+\s+)?кеш|немає\s+кеш/i
 const CRITIC_NONE_RE = /^\s*NONE\s*$/i
+// R4: абстрактні «нічого-не-кажучі» формули, які обходять exact-blocklist і дають score=100
+const GENERIC_RE =
+  /відповідност\S*\s+(?:даних\s+)?(?:визначеному\s+)?контракту|валідаці\S*\s+даних|перевірк\S*\s+(?:відповідності\s+)?даних|обробк\S*\s+даних|застосову\S*\s+логіку|інспекту\S*\s+та\s+збира\S*\s+дан/i
+// R7: часті русизми/суржик (курований безпечний список — без false-positive на нормальній мові).
+// Без \b: кирилиця не є ASCII-`\w`, тож межі слова в JS-regex не спрацьовують — терміни специфічні.
+const SURZHIK_RE =
+  /пропуская|являється|в залежності|по замовчуванню|на протязі|відповідаюч|слідуюч|наступним разом|приймати участь|у відповідності/i
+const ANCHOR_MISS_PENALTY = 5
+const ANCHOR_MISS_CAP = 20
 
 /**
  * Прибирає код-фенс-обгортку (потрійні бектіки) й випадковий провідний
@@ -86,18 +96,26 @@ function hasName(text, sym) {
  * Stage 2.5 — детермінований скоринг (0 токенів): перевіряє вихід проти фактів.
  * @param {string} md зібраний документ
  * @param {object} facts факт-лист про файл
+ * @param {{ anchors?: object|null, src?: string }} [ctx] анкори й джерело для R5
  * @returns {{ score: number, issues: string[] }} оцінка 0–100 і коди проблем
  */
-function scoreDoc(md, facts) {
+export function scoreDoc(md, facts, { anchors = null, src = '' } = {}) {
   const s = parseSections(md)
   let score = 100
   const issues = []
+  const overview = s['огляд'] ?? ''
 
   if (!s['огляд']) {
     score -= 25
     issues.push('no-overview')
   }
 
+  // R4: generic-Огляд (парафрази, які обходять exact-blocklist) — як майже-відсутній.
+  if (GENERIC_RE.test(overview)) {
+    score -= 35
+    issues.push('generic-overview')
+  }
+
   const behavior = s['поведінка'] ?? ''
   if (behavior.length < 60) {
     score -= 20
@@ -113,14 +131,35 @@ function scoreDoc(md, facts) {
     issues.push('cache-hallucination')
   }
 
-  for (const sym of facts.internalSymbols ?? []) {
-    const inDoc = hasName(guarantees, sym) || hasName(s['огляд'] ?? '', sym) || hasName(s['поведінка'] ?? '', sym)
+  // R6: службові (неекспортовані) функції не мають фігурувати як публічні
+  const api = s['публічнийapi'] ?? ''
+  for (const sym of [...(facts.internalSymbols ?? []), ...(facts.localSymbols ?? [])]) {
+    const inDoc = hasName(guarantees, sym) || hasName(overview, sym) || hasName(behavior, sym) || hasName(api, sym)
     if (inDoc) {
       score -= 10
       issues.push(`internal-name:${sym}`)
     }
   }
 
+  // R5: кожен валідний анкор (дослівний підрядок src) має зʼявитися в документі
+  if (anchors && src) {
+    let missPenalty = 0
+    for (const tok of anchorTokens(anchors)) {
+      if (!src.includes(tok)) continue // валідність: фейковий анкор не вимагаємо
+      if (!md.includes(tok) && missPenalty < ANCHOR_MISS_CAP) {
+        missPenalty += ANCHOR_MISS_PENALTY
+        issues.push(`anchor-miss:${tok}`)
+      }
+    }
+    score -= missPenalty
+  }
+
+  // R7: суржик/русизми
+  if (SURZHIK_RE.test(md)) {
+    score -= 10
+    issues.push('surzhik')
+  }
+
   return { score: Math.max(0, score), issues }
 }
 
@@ -205,15 +244,21 @@ function orchestratedDoc(facts, src, model, timeoutMs, { anchors = null, tempera
   const anc = anchors ?? extractAnchors(src)
   // E3: «Гарантії» — детермінований шаблон з markers (0 LLM-запитів, 0 generic-фраз)
   sections.guarantees = guaranteesFromMarkers(facts)
+  // Спершу Поведінка (+API) — секції з фактажем
   for (const s of sectionMessages(facts, src, anc)) {
-    if (s.key === 'guarantees') continue // вже згенеровано детерміновано
     let draft = stripSignatures(stripSection(callLlm(s.messages, model, { timeoutMs, temperature })))
-    // E2 + E3: critique→refine лише для секцій, де мала модель зриває на generic
-    if (s.key === 'overview' || (s.key === 'api' && apiNeedsRefine(facts))) {
+    // E2: critique→refine для API, коли всі описи порожні (модель зриває на generic)
+    if (s.key === 'api' && apiNeedsRefine(facts)) {
       draft = critiqueRefineSection(s.key, draft, facts, anc, model, timeoutMs)
     }
     sections[s.key] = draft
   }
+  // R3: «Огляд» — ОСТАННІМ, узагальненням уже написаної Поведінки (не голого факт-листа)
+  let overview = stripSignatures(
+    stripSection(callLlm(overviewMessages(facts, sections.behavior ?? '', anc), model, { timeoutMs, temperature }))
+  )
+  overview = critiqueRefineSection('overview', overview, facts, anc, model, timeoutMs)
+  sections.overview = overview
   return { md: assemble(basename(facts.relPath), sections) }
 }
 
@@ -253,13 +298,13 @@ export function generateDoc(file, { model = DEFAULT_LOCAL_MODEL, threshold = QUA
   }
 
   // Stage 2.5: детермінований скоринг (0 токенів)
-  let { score, issues } = scoreDoc(r.md, facts)
+  let { score, issues } = scoreDoc(r.md, facts, { anchors, src })
 
   // E4: best-of-2 — один retry з вищою температурою, det-вибір кращого
   if (score < threshold && env.N_CURSOR_DOCGEN_BEST_OF !== '0') {
     try {
       const r2 = orchestratedDoc(facts, src, model, LOCAL_TIMEOUT_MS, { anchors, temperature: 0.5 })
-      const s2 = scoreDoc(r2.md, facts)
+      const s2 = scoreDoc(r2.md, facts, { anchors, src })
       if (s2.score > score) {
         r = r2
         score = s2.score

package/skills/doc-files/js/docgen-prompts.mjs

@@ -52,31 +52,26 @@ const msgs = (system, user) => [
 
 /**
  * Секційні набори messages з МІНІМАЛЬНИМ контекстом під кожну секцію.
- * Код потрапляє лише в `behavior`; решта секцій — на факт-листі.
+ * Код потрапляє лише в `behavior`; «Огляд» генерується окремо ОСТАННІМ
+ * (`overviewMessages`) з уже написаної Поведінки — тут його немає.
  * @param {object} facts факт-лист про файл
  * @param {string} src вміст файлу
  * @param {object|null} [anchors] анкори файлу для обовʼязкового включення
- * @returns {Array<{key:string, messages:object[], numPredict:number}>} набір секційних промптів
+ * @returns {Array<{key:string, messages:object[], numPredict:number}>} набір секційних промптів (behavior[, api])
  */
 export function sectionMessages(facts, src, anchors = null) {
   const factsTxt = factsSummary(facts)
   const anch = anchorsBlock(anchors)
   const multi = (facts.exports?.length || 0) > 1
 
-  // Огляд — лише факти (без коду)
-  const overview = {
-    key: 'overview',
-    numPredict: 220,
-    messages: msgs(
-      `${STYLE}\n\nВІДОМІ ФАКТИ:\n${factsTxt}${anch}`,
-      'Напиши вміст секції «Огляд»: 1-3 речення — що файл робить і навіщо існує (роль у системі). Без заголовка, без переліку функцій. Заборонені generic-фрази типу «забезпечує перевірку», «виконує валідацію» — пиши КОНКРЕТНО що саме і за яким контрактом.'
-    )
-  }
-
-  // Поведінка — ЄДИНА секція, якій потрібен код
+  // R6: Поведінка описує РІВНО експортовані імена, не службові помічники
+  const exportNames = (facts.exports ?? []).map(e => e.name)
   const behaviorTask = multi
     ? 'для кожної публічної функції — один короткий пункт «що вона робить»'
     : 'нумерований алгоритм у бізнес-термінах'
+  const onlyExports = exportNames.length
+    ? ` Описуй РІВНО ці публічні імена і жодних інших: ${exportNames.join(', ')}.`
+    : ''
   const noInternal = facts.internalSymbols?.length
     ? ` НЕ згадуй за іменами службові функції: ${facts.internalSymbols.join(', ')}.`
     : ''
@@ -85,12 +80,12 @@ export function sectionMessages(facts, src, anchors = null) {
     numPredict: 500,
     messages: msgs(
       `${STYLE}\n\nФАЙЛ ${facts.relPath}:\n\`\`\`\n${src}\n\`\`\`\n\nВІДОМІ ФАКТИ:\n${factsTxt}${anch}`,
-      `Напиши вміст секції «Поведінка»: ${behaviorTask}. Якщо у фактах є свідомі пропуски шляхів — згадай їх там, де доречно (не вигадуй інших «не перевіряє»). НЕ пиши аргументи функцій у дужках, без regex.${noInternal} Без заголовка, без додаткових ## чи # підзаголовків усередині секції.`
+      `Напиши вміст секції «Поведінка»: ${behaviorTask}.${onlyExports} Якщо у фактах є свідомі пропуски шляхів — згадай їх там, де доречно (не вигадуй інших «не перевіряє»). НЕ пиши аргументи функцій у дужках, без regex.${noInternal} Без заголовка, без додаткових ## чи # підзаголовків усередині секції.`
     )
   }
 
   // API — лише список експортів (без коду)
-  if (!multi && !facts.exports?.some(e => e.desc)) return [overview, behavior]
+  if (!multi && !facts.exports?.some(e => e.desc)) return [behavior]
   const list = facts.exports.map(e => `- ${e.name}: ${e.desc || '(сформулюй стисло з наміру файлу)'}`).join('\n')
   const api = {
     key: 'api',
@@ -100,7 +95,24 @@ export function sectionMessages(facts, src, anchors = null) {
       `Перепиши цей список як стислі маркери «назва — що робить», СВОЇМИ словами (не копіюй дослівно), без типів і сигнатур. Використовуй РІВНО ці назви, не додавай і не прибирай:\n${list}\nБез заголовка. Без generic-фраз «застосовує логіку», «перевіряє коректність» — пиши конкретно ЩО саме застосовує/перевіряє.`
     )
   }
-  return [overview, behavior, api]
+  return [behavior, api]
+}
+
+/**
+ * R3 — «Огляд» ОСТАННІМ: узагальнення вже написаної Поведінки, а не здогад із
+ * голого факт-листа. Лікує generic/хибний Огляд на складних файлах.
+ * @param {object} facts факт-лист про файл
+ * @param {string} behaviorText готовий текст секції «Поведінка»
+ * @param {object|null} [anchors] анкори файлу
+ * @returns {Array<{role:string,content:string}>} messages-масив для Огляду
+ */
+export function overviewMessages(facts, behaviorText, anchors = null) {
+  const factsTxt = factsSummary(facts)
+  const anch = anchorsBlock(anchors)
+  return msgs(
+    `${STYLE}\n\nВІДОМІ ФАКТИ:\n${factsTxt}${anch}`,
+    `На основі вже написаної секції «Поведінка» (нижче) напиши «Огляд»: 1-3 речення — що файл робить і навіщо існує (роль у системі). Узагальнюй САМЕ описану поведінку, не додавай нових фактів. Без заголовка, без переліку функцій. Заборонені абстрактні формули без конкретики («перевірка/валідація/обробка даних», «відповідність контракту», «застосовує логіку») — пиши, ЩО саме і за яким контрактом.\n\nПОВЕДІНКА:\n${behaviorText}`
+  )
 }
 
 /**

package/skills/doc-files/js/units-js.mjs

@@ -0,0 +1,139 @@
+/** @see ./docs/units-js.md */
+
+import { parseProgramOrNull, walkAstWithAncestors } from '../../../scripts/utils/ast-scan-utils.mjs'
+
+// JSDoc-блок, що стоїть впритул перед позицією (лише пробіли між ними).
+const JSDOC_BEFORE_RE = /\/\*\*(?:(?!\*\/)[\s\S])*\*\/\s*$/
+const JSDOC_OPEN_RE = /^\s*\/\*\*?/
+const JSDOC_CLOSE_RE = /\*\/\s*$/
+const STAR_PREFIX_RE = /^\s*\*?\s?/
+
+/**
+ * Очищає JSDoc від обрамлення `/** *​/` і `*`-префіксів.
+ * @param {string} raw сирий блок або порожній рядок
+ * @returns {string} текст опису без тегів-обрамлення
+ */
+function cleanDoc(raw) {
+  if (!raw) return ''
+  return raw
+    .replace(JSDOC_OPEN_RE, '')
+    .replace(JSDOC_CLOSE_RE, '')
+    .split('\n')
+    .map(l => l.replace(STAR_PREFIX_RE, '').trimEnd())
+    .join('\n')
+    .trim()
+}
+
+/**
+ * JSDoc, що передує позиції `start` у джерелі (або порожній рядок).
+ * @param {string} src вміст файлу
+ * @param {number} start зміщення початку декларації
+ * @returns {string} очищений опис
+ */
+function precedingDoc(src, start) {
+  const m = src.slice(0, start).match(JSDOC_BEFORE_RE)
+  return cleanDoc(m ? m[0] : '')
+}
+
+/**
+ * Імʼя функції, що викликається (проста Identifier або `obj.method`).
+ * @param {Record<string, unknown>} node CallExpression
+ * @returns {string|null} імʼя callee або null
+ */
+function calleeName(node) {
+  const c = node.callee
+  if (!c || typeof c !== 'object') return null
+  if (c.type === 'Identifier') return c.name
+  if (c.type === 'MemberExpression' && !c.computed && c.property?.type === 'Identifier') return c.property.name
+  return null
+}
+
+/**
+ * Множина імен, що викликаються у тілі вузла (сирі callee — фільтрація на ребра
+ * call-graph робиться у `extractUnitsJs` після збору всіх імен юнітів).
+ * @param {unknown} node AST-вузол юніта
+ * @returns {Set<string>} імена викликів
+ */
+function collectCalls(node) {
+  const names = new Set()
+  walkAstWithAncestors(node, [], n => {
+    if (n.type === 'CallExpression') {
+      const name = calleeName(n)
+      if (name) names.add(name)
+    }
+  })
+  return names
+}
+
+/**
+ * Будує юніт із декларації, додає у `units`. Розпізнає function/class та
+ * const-функції (`const x = () => {}` / `function expression`).
+ * @param {Record<string, unknown>} decl декларація (function/class/variable)
+ * @param {boolean} exported чи експортується
+ * @param {number} docStart зміщення для пошуку JSDoc (зовнішній export-вузол)
+ * @param {string} src вміст файлу
+ * @param {Array<object>} units акумулятор
+ * @returns {void}
+ */
+function pushUnits(decl, exported, docStart, src, units) {
+  if (!decl || typeof decl !== 'object') return
+  const doc = precedingDoc(src, docStart)
+  if (decl.type === 'FunctionDeclaration' || decl.type === 'ClassDeclaration') {
+    const name = decl.id?.name
+    if (!name) return
+    units.push({
+      name,
+      kind: decl.type === 'ClassDeclaration' ? 'class' : 'function',
+      exported,
+      span: { start: decl.start, end: decl.end },
+      body: src.slice(decl.start, decl.end),
+      calls: collectCalls(decl),
+      doc
+    })
+    return
+  }
+  if (decl.type === 'VariableDeclaration') {
+    for (const d of decl.declarations ?? []) {
+      const init = d.init
+      const isFn = init && (init.type === 'ArrowFunctionExpression' || init.type === 'FunctionExpression')
+      if (!isFn || d.id?.type !== 'Identifier') continue
+      units.push({
+        name: d.id.name,
+        kind: 'const',
+        exported,
+        span: { start: init.start, end: init.end },
+        body: src.slice(init.start, init.end),
+        calls: collectCalls(init),
+        doc
+      })
+    }
+  }
+}
+
+/**
+ * Юніт-шар для js/mjs/ts: top-level функції/класи/const-функції з тілом, JSDoc,
+ * прапором експорту і ребрами call-graph (виклики ІНШИХ юнітів у тілі).
+ * @param {string} src вміст файлу
+ * @param {string} [relPath] шлях (для вибору мови oxc)
+ * @returns {Array<{name:string, kind:string, exported:boolean, span:{start:number,end:number}, body:string, calls:string[], doc:string}>|null} юніти або null, якщо файл не парситься
+ */
+export function extractUnitsJs(src, relPath = 'scan.ts') {
+  const program = parseProgramOrNull(src, relPath)
+  if (!program || !Array.isArray(program.body)) return null
+
+  const units = []
+  for (const node of program.body) {
+    if (node.type === 'ExportNamedDeclaration' && node.declaration) {
+      pushUnits(node.declaration, true, node.start, src, units)
+    } else if (node.type === 'ExportDefaultDeclaration' && node.declaration) {
+      pushUnits(node.declaration, true, node.start, src, units)
+    } else {
+      pushUnits(node, false, node.start, src, units)
+    }
+  }
+
+  // Ребра call-graph: лишаємо тільки виклики інших внутрішніх юнітів
+  const names = new Set(units.map(u => u.name))
+  for (const u of units) u.calls = [...u.calls].filter(n => names.has(n) && n !== u.name)
+  return units
+}

package/skills/doc-files/js/units.mjs

@@ -0,0 +1,19 @@
+/** @see ./docs/units.md */
+
+import { extractUnitsJs } from './units-js.mjs'
+
+const JS_EXT = new Set(['js', 'mjs', 'ts', 'jsx', 'tsx', 'cts', 'mts'])
+
+/**
+ * Мовно-агностичний фасад юніт-шару (Інкремент 1). Диспатчить за розширенням:
+ * js/mjs/ts → oxc; vue/py — додаються наступними кроками (поки `null` → виклик
+ * відкочується на whole-file шлях, як і раніше).
+ * @param {string} src вміст файлу
+ * @param {string} relPath шлях файлу
+ * @returns {Array<object>|null} юніти або null, якщо мова ще не підтримана / файл не парситься
+ */
+export function extractUnits(src, relPath) {
+  const ext = (relPath.split('.').pop() || '').toLowerCase()
+  if (JS_EXT.has(ext)) return extractUnitsJs(src, relPath)
+  return null
+}

package/skills/fix/js/llm-worker.mjs

@@ -2,10 +2,9 @@
 
 import { existsSync, readFileSync, writeFileSync } from 'node:fs'
 import { join } from 'node:path'
-import { spawnSync } from 'node:child_process'
 import { env } from 'node:process'
 import { resolveModel } from '../../../lib/models.mjs'
-import { callOmlx, isOmlxModel } from '../../../lib/omlx.mjs'
+import { callLlm } from '../../../lib/llm.mjs'
 
 // Тир за замовчуванням: min → avg при ескалації (каскад local→cloud).
 // Перевизначення через N_CURSOR_FIX_MODEL / N_CURSOR_FIX_MODEL_HEAVY.
@@ -13,6 +12,7 @@ export const MODEL = env.N_CURSOR_FIX_MODEL ?? resolveModel('min')
 export const MODEL_HEAVY = env.N_CURSOR_FIX_MODEL_HEAVY ?? resolveModel('avg')
 
 const JSON_CODE_BLOCK_RE = /```(?:json)?[ \t]{0,8}\n?([\s\S]*?)```/
+const API_KEY_RE = /api key/i
 
 /**
  * Витягує відносні шляхи файлів із violation output.
@@ -87,29 +87,18 @@ function buildPrompt(ruleId, ruleMdc, output, files) {
 }
 
 /**
- * Викликає LLM за model-id і повертає текст відповіді.
- * `omlx/...` → прямий HTTP до omlx (text-only, локально); решта → pi CLI.
+ * Викликає LLM через спільний `callLlm` (маршрут за префіксом model-id; wire-trace).
+ * Зберігає дружнє повідомлення про відсутній API-ключ для хмарних провайдерів.
  * @param {string} prompt текст промпта
  * @param {string} model назва моделі (provider/id, `omlx/...` або '')
  * @returns {{ text: string, error?: string }} текст відповіді або повідомлення про помилку
  */
 function callModel(prompt, model) {
-  if (isOmlxModel(model)) {
-    try {
-      return { text: callOmlx([{ role: 'user', content: prompt }], model, { timeoutMs: 120_000 }) }
-    } catch (error) {
-      return { text: '', error: error.message }
-    }
-  }
-  const modelArgs = model ? ['--model', model] : []
-  const r = spawnSync('pi', ['-p', prompt, ...modelArgs, '--no-session', '--mode', 'text', '--no-tools'], {
-    encoding: 'utf8',
-    timeout: 120_000
-  })
-  if (r.error) return { text: '', error: r.error.message }
-  if (r.status !== 0) {
-    const stderr = r.stderr?.slice(0, 300) ?? ''
-    if (stderr.toLowerCase().includes('no api key') || stderr.toLowerCase().includes('api key')) {
+  try {
+    return { text: callLlm([{ role: 'user', content: prompt }], model, { timeoutMs: 120_000, caller: 'fix' }) }
+  } catch (error) {
+    const msg = String(error.message)
+    if (API_KEY_RE.test(msg)) {
       const provider = model ? model.split('/')[0] : 'дефолтного провайдера'
       return {
         text: '',
@@ -120,9 +109,8 @@ function callModel(prompt, model) {
         ].join(' ')
       }
     }
-    return { text: '', error: `pi exit ${r.status}: ${stderr}` }
+    return { text: '', error: msg }
   }
-  return { text: r.stdout?.trim() ?? '' }
 }
 
 /**