@nitra/cursor 5.3.2 → 5.3.4

package/skills/doc-files/js/docs/docgen-gen.md

@@ -1,30 +1,46 @@
 ---
 docgen:
   source: npm/skills/doc-files/js/docgen-gen.mjs
-  crc: 2d6e5f79
+  crc: e2af04d6
+  score: 100
 ---
 
-# docgen-gen
+# docgen-gen.mjs
 
 ## Огляд
 
-Генератор однієї файлової доки local-only конвеєра: файл → українська поведінкова md-документація локальною моделлю, з детермінованим скорингом і позначкою degraded замість будь-яких хмарних ескалацій.
+Огляд
+Публічні функції виконують операції з текстом та оцінками. Вони включають виділення коду, вставлення інформації та генерацію документів на основі визначених параметрів.
 
 ## Поведінка
 
-1. З джерела детерміновано витягуються факти (намір файлу, експорти, маркери поведінки) та анкори (URL, константи, маркери помилок, конфіги, приклади з header-коментаря) — без жодного токена.
-2. Для підтримуваних структур документ збирається посекційно окремими викликами моделі: «Огляд» — лише з фактів, «Поведінка» — єдина секція з кодом у вікні, «Публічний API» — зі списку експортів; «Гарантії поведінки» — детермінований шаблон із маркерів без LLM. Для непідтримуваних структур (`vue`/`py` до появи юніт-шару) — один виклик на весь документ без скорингу.
-3. Чорнетки секцій проходять детермінований пост-лінт (зрізання сигнатур, обгорток, випадкових заголовків); найвразливіші секції — один цикл критика-редактора.
-4. Зібраний документ оцінюється детермінованим скорером (наявність огляду, змістовність поведінки, галюцинація кешу, витік внутрішніх імен). Якщо оцінка нижча за поріг — один повторний прогін з вищою температурою, перемагає кращий за оцінкою (вимикається `N_CURSOR_DOCGEN_BEST_OF=0`).
-5. Результат повертається з оцінкою, списком проблем і прапором degraded; рішення про повторну генерацію приймає batch-обгортка або користувач — конвеєр ніколи не звертається до хмари.
+splitProtected
+Вибирає та видаляє код-фенс-обгортку з секції
+
+insertProtected
+Вставляє захищений блок Призначення після заголовка Огляд
+
+scoreDoc
+Перевіряє вихід проти фактів і повертає оцінку та список проблем
+
+DEFAULT_LOCAL_MODEL
+Повертає дефолтну модель для роботи
+
+generateDoc
+Генерує документ з детермінованою оцінкою та метаданими
 
 ## Публічний API
 
-- `generateDoc` — головна точка: шлях файлу → `{ md, ms, score, issues, degraded, model }`.
-- `DEFAULT_LOCAL_MODEL` — модель конвеєра: `N_CURSOR_DOCGEN_MODEL` → каскад локальних тирів → локальний omlx-дефолт напряму.
+splitProtected — Відокремлює захищену секцію `## Призначення` (Варіант B). Межа — наступний `## ` і `###` не обриває блок. (abie.mdc)
+insertProtected — Вставляє захищений блок `## Призначення` одразу після H1 (фіксована позиція). (abie.mdc)
+scoreDoc — Stage 2.5 — Детермінований скоринг (0 токенів): перевіряє вихід проти фактів. (abie.mdc)
+DEFAULT_LOCAL_MODEL — Дефолтна модель: N_CURSOR_DOCGEN_MODEL → resolveModel → omlx напряму. Останній fallback гарантує локальний виклик без змін середовища (через pi CLI той самий локальний виклик виміряно повільніший на ~46%). (abie.mdc)
+generateDoc — Головний API: файл → md-дока з det-оцінкою. (abie.mdc)
 
 ## Гарантії поведінки
 
-- Local-only: жодних хмарних викликів і pre-route за складністю — будь-який файл генерується локальною моделлю.
-- Скоринг і пост-лінт детерміновані: однаковий вхід → однакова оцінка.
-- Помилка транспорту прокидається назовні — не маскується під degraded.
+- Read-only: файл не виконує операцій запису у файлову систему.
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).
+- За невдачі повертає значення помилки (`false`/`null`/`Err`) замість генерування винятку чи паніки.
+- Кешує результати в межах одного прогону.
+- Не звертається до мережі.

package/skills/doc-files/js/docs/docgen-ignore.md

@@ -0,0 +1,37 @@
+---
+docgen:
+  source: npm/skills/doc-files/js/docgen-ignore.mjs
+  crc: f9206fe0
+  score: 100
+---
+
+# docgen-ignore.mjs
+
+## Огляд
+
+DOCGEN_IGNORE_GLOBS
+Список шляхів, які docgen повинен ігнорувати.
+
+isDocgenIgnored
+Перевіряє, чи вказаний шлях знаходиться у списку ігнорованих шляхів. Повертає булеве значення.
+
+## Поведінка
+
+DOCGEN_IGNORE_GLOBS
+Базовий список glob-ів для docgen ignore
+
+isDocgenIgnored
+Перевіряє, чи шлях має бути пропущений docgen
+
+## Публічний API
+
+DOCGEN_IGNORE_GLOBS — Базовий список glob-ів для ігнорування у `docgen`.
+isDocgenIgnored — Визначає, чи шлях повинен бути пропущений `docgen`. Для `kind = 'dir'` працює і на підкаталоги, наприклад, `**\\/demo/**` спрацьовує на `demo/x` під час рекурсивного обходу.
+
+## Гарантії поведінки
+
+- Read-only: файл не виконує операцій запису у файлову систему.
+- За невдачі повертає значення помилки (`false`/`null`/`Err`) замість генерування винятку чи паніки.
+- Кешує результати в межах одного прогону.
+- Свідомо пропускає шляхи: `.git`, `node_modules`.
+- Не звертається до мережі.

package/skills/doc-files/js/docs/units-rs.md

@@ -0,0 +1,35 @@
+---
+docgen:
+  source: npm/skills/doc-files/js/units-rs.mjs
+  crc: 11099381
+  score: 100
+---
+
+# units-rs.mjs
+
+## Огляд
+
+Файл аналізує рядки для визначення структури та елементів модуля. Він ітерує по рядках для визначення глибини, обробляє рядкові літерали для визначення зміщення, змінює глибину при зустрічі відкриваючої чи закриваючої фігу, видаляє відкриті блоки зі стека, перевіряє наявність атрибутів експонування, визначає декларації на верхньому рівні чи в модулях, а також витягує тіло функції та збирає виклики інших юнітів у тілі функції.
+
+## Поведінка
+
+1. Скан файлу по рядках.
+2. Ітерація по рядках для визначення глибини.
+3. Обробка рядкових літералів для визначення зміщення.
+4. Зміна глибини при зустрічі відкриваючої фігу.
+5. Зміна глибини при зустрічі закриваючої фігу.
+6. Видалення відкритих блоків з стека.
+7. Перевірка наявності атрибутів експонування.
+8. Визначення декларацій на верхньому рівні або в модулях.
+9. Визначення публічних функцій, структур, перерахувань, трейтів, типів.
+10. Витягування тіла функції через пошук закриваючої фігу.
+11. Збір викликів інших юнітів у тілі функції.
+
+## Публічний API
+
+extractUnitsRs — Визначає top-level і impl-методи через підрахунок дужок по рядках. Обмеження: рядкові літерали з `{`/`}` всередині `{}` можуть дати хибну глибину.
+
+## Гарантії поведінки
+
+- Read-only: файл не виконує операцій запису у файлову систему.
+- Не звертається до мережі.

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

@@ -0,0 +1,213 @@
+/** @see ./docs/units-rs.md */
+
+/**
+ * Пропускає рядковий літерал `"..."` (з escape-послідовностями).
+ * @param {string} src вміст файлу
+ * @param {number} i позиція відкриваючого `"`
+ * @returns {number} позиція ПІСЛЯ закриваючого `"`
+ */
+function skipString(src, i) {
+  i++ // відкриваючий "
+  while (i < src.length) {
+    if (src[i] === '\\') { i += 2; continue }
+    if (src[i] === '"') return i + 1
+    i++
+  }
+  return i
+}
+
+/**
+ * Знаходить індекс закриваючої `}` для відкриваючої `{` на позиції `start`.
+ * Правильно пропускає рядки/блочні коментарі та рядкові літерали.
+ * @param {string} src вміст файлу
+ * @param {number} start позиція відкриваючої `{`
+ * @returns {number} індекс `}` або -1, якщо не знайдено
+ */
+function findClosingBrace(src, start) {
+  let depth = 0
+  let i = start
+  while (i < src.length) {
+    const ch = src[i]
+    if (ch === '/' && src[i + 1] === '/') {
+      const nl = src.indexOf('\n', i)
+      i = nl === -1 ? src.length : nl + 1
+      continue
+    }
+    if (ch === '/' && src[i + 1] === '*') {
+      const end = src.indexOf('*/', i + 2)
+      i = end === -1 ? src.length : end + 2
+      continue
+    }
+    if (ch === '"') { i = skipString(src, i); continue }
+    if (ch === '{') { depth++; i++; continue }
+    if (ch === '}') {
+      depth--
+      if (depth === 0) return i
+      i++
+      continue
+    }
+    i++
+  }
+  return -1
+}
+
+/**
+ * Видобуває `///` doc-рядки безпосередньо перед рядком `lineIdx`.
+ * Сканує назад через `///`, `#[...]` та пусті рядки.
+ * @param {string[]} lines рядки файлу
+ * @param {number} lineIdx рядок декларації
+ * @returns {string} склеєний опис або ''
+ */
+function docBefore(lines, lineIdx) {
+  const doc = []
+  for (let i = lineIdx - 1; i >= 0; i--) {
+    const t = lines[i].trim()
+    if (t.startsWith('///')) {
+      doc.unshift(t.slice(3).trim())
+    } else if (t.startsWith('#[') || t.startsWith('#![') || t === '') {
+      // пропустити атрибути та пусті рядки
+    } else {
+      break
+    }
+  }
+  return doc.join(' ').trim()
+}
+
+// Pub-items: pub fn / pub struct / pub enum / pub trait / pub type
+// Також ловить fn без pub (для localSymbols і impl-методів)
+const ITEM_RE = /^[ \t]*(pub(?:\([^)]*\))?\s+)?(?:async\s+)?(?:unsafe\s+)?(fn|struct|enum|trait|type)\s+(\w+)/
+
+// impl Type { або impl<T> Trait for Type {
+const IMPL_RE = /^[ \t]*(?:pub\s+)?impl(?:<[^>]*>)?\s+(?:(?:\w[\w:<>, ]*\s+for\s+))?(\w+)/
+
+// Підозрілі exposure-атрибути, що роблять непуб-fn фактично публічними
+const EXPOSURE_ATTR_RE = /#\[(?:tauri::command|wasm_bindgen|uniffi::export|pyo3::pyfunction|napi)/
+
+// Базовий виклик fn-імені (для call-graph всередині юніта)
+const CALL_RE = /\b([a-z_]\w*)\s*\(/g
+
+/**
+ * Юніт-екстрактор для `.rs` файлів.
+ * Визначає top-level і impl-методи через підрахунок дужок по рядках.
+ * Відомі обмеження: рядкові літерали з `{`/`}` всередині `{}` можуть дати
+ * хибну глибину (рідкісно в реальному Rust-коді з rustfmt).
+ * @param {string} src вміст файлу
+ * @param {string} [_relPath] резервний (не використовується)
+ * @returns {Array<{name:string, kind:string, exported:boolean, implName:string|null, span:{start:number,end:number}, body:string, calls:string[], doc:string}>|null}
+ */
+export function extractUnitsRs(src, _relPath) {
+  const lines = src.split('\n')
+  const units = []
+  let depth = 0
+  let lineOffset = 0
+  // Стек відкритих impl: { typeName, openDepth }
+  const implStack = []
+  // Флаг: наступний fn отримує exposure (через #[tauri::command] тощо)
+  let nextFnExposed = false
+
+  for (let li = 0; li < lines.length; li++) {
+    const line = lines[li]
+    const depthAtStart = depth
+
+    // Підраховуємо `{` і `}` в рядку (пропускаємо рядкові коментарі та рядки)
+    let j = 0
+    while (j < line.length) {
+      const ch = line[j]
+      if (ch === '/' && line[j + 1] === '/') break
+      if (ch === '"') {
+        j++
+        while (j < line.length && line[j] !== '"') {
+          if (line[j] === '\\') j++
+          j++
+        }
+        j++
+        continue
+      }
+      if (ch === '{') depth++
+      else if (ch === '}') depth--
+      j++
+    }
+
+    // Закриті impl-блоки прибираємо зі стека
+    while (implStack.length > 0 && implStack[implStack.length - 1].openDepth > depth) {
+      implStack.pop()
+    }
+
+    const currentImpl = implStack.at(-1)?.typeName ?? null
+
+    // Перевіряємо exposure-атрибути
+    if (EXPOSURE_ATTR_RE.test(line)) {
+      nextFnExposed = true
+    }
+
+    // Impl-декларація (зазвичай глибина 0, але може бути в mod)
+    if (depthAtStart <= 1) {
+      const implM = line.match(IMPL_RE)
+      if (implM && line.includes('{')) {
+        implStack.push({ typeName: implM[1], openDepth: depth })
+      }
+    }
+
+    // Елементи на глибині 0 (top-level) і 1 (всередині impl)
+    if (depthAtStart <= 1) {
+      const m = line.match(ITEM_RE)
+      if (m) {
+        const isPub = Boolean(m[1]) || (m[2] === 'fn' && nextFnExposed)
+        if (m[2] === 'fn') nextFnExposed = false
+        const kind = m[2]
+        const name = m[3]
+        const doc = docBefore(lines, li)
+
+        // Витягуємо тіло через findClosingBrace для fn/struct/enum/trait
+        let body = ''
+        let itemEnd = lineOffset + line.length
+        if (kind !== 'type') {
+          const openBraceIdx = src.indexOf('{', lineOffset)
+          // Шукаємо `{` не далі ніж через 3 рядки від початку декларації
+          const threeLines = lines.slice(li, li + 3).join('\n').length
+          if (openBraceIdx !== -1 && openBraceIdx - lineOffset <= threeLines) {
+            const closeIdx = findClosingBrace(src, openBraceIdx)
+            if (closeIdx !== -1) {
+              itemEnd = closeIdx + 1
+              body = src.slice(lineOffset, itemEnd)
+            }
+          }
+        }
+
+        units.push({
+          name,
+          kind,
+          exported: isPub,
+          implName: depthAtStart === 1 ? currentImpl : null,
+          span: { start: lineOffset, end: itemEnd },
+          body,
+          calls: [],
+          doc
+        })
+      } else {
+        // Рядок не є item — скидаємо exposure-флаг якщо не атрибут
+        const t = line.trim()
+        if (!t.startsWith('#[') && !t.startsWith('#![') && !t.startsWith('///') && t !== '') {
+          nextFnExposed = false
+        }
+      }
+    }
+
+    lineOffset += line.length + 1 // +1 для '\n'
+  }
+
+  // Базовий call-graph: виклики інших юнітів цього файлу
+  const unitNames = new Set(units.map(u => u.name))
+  for (const u of units) {
+    if (!u.body) continue
+    const calls = new Set()
+    let cm
+    const re = new RegExp(CALL_RE.source, 'g')
+    while ((cm = re.exec(u.body)) !== null) {
+      if (unitNames.has(cm[1]) && cm[1] !== u.name) calls.add(cm[1])
+    }
+    u.calls = [...calls]
+  }
+
+  return units.length > 0 ? units : null
+}

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

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