@nitra/cursor 5.3.3 → 5.3.4

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## [5.3.4] - 2026-06-11
+
+### Changed
+
+- ✨ feat(npm/skills/doc-files): Rust (.rs): тести extractFactsRust у docg…
+
 ## [5.3.3] - 2026-06-11
 
 ### Changed

package/lib/docs/llm.md

@@ -1,29 +1,40 @@
 ---
 docgen:
   source: npm/lib/llm.mjs
-  crc: 9ef9f20f
+  crc: a70a8328
+  score: 100
 ---
 
-# llm
+# llm.mjs
 
 ## Огляд
 
-Єдина точка LLM-викликів для JS-оркестраторів монорепо: ховає вибір транспорту за конвенцією префікса model-id і дає preflight-перевірку локального сервера перед масовими прогонами.
+Файл надає механізми для виклику великих мовних моделей. Маршрутизація вибору транспортного каналу залежить від префікса ідентифікатора моделі згідно з конвенцією `npm/lib/models.mjs`. Виклик LLM виконує виклик з визначеною маршрутизацією та запис трасування. Перевірка стану omlx сервера визначає доступність моделі.
 
 ## Поведінка
 
-1. Виклик із model-id з префіксом `omlx/` іде прямим HTTP до локального omlx-сервера зі збереженням ролей повідомлень; будь-який інший model-id (зокрема порожній) — через `pi` CLI, де повідомлення конкатенуються в один текстовий промпт, а інструменти вимкнено.
-2. Якщо виставлено `N_CURSOR_LLM_TRACE` зі шляхом до файлу, кожен виклик дописує один JSONL-рядок: бекенд, модель, тривалість, розміри промпта/відповіді, успіх або текст помилки. Невдалий запис трейсу не впливає на сам виклик.
-3. Preflight локального сервера робить мінімальний запит (одна позиція виходу) і класифікує стан: сервер лежить (`down`), модель не влазить у динамічну стелю пам'яті зайнятої машини (`memory-guard`), сервер вимагає API-ключ (`auth`), інша помилка (`error`). Порожня відповідь живого сервера вважається здоровим станом.
+pickBackend
+Маршрутизує модель по префіксу до визначеного бекенда
+
+callLlm
+Виконує універсальний виклик LLM з маршрутизацією за моделью та wire-trace
+
+omlxHealthCheck
+Перевіряє стан omlx сервера для визначення доступності моделі
 
 ## Публічний API
 
-- `callLlm` — універсальний виклик за messages-масивом із маршрутизацією за префіксом model-id.
-- `pickBackend` — назва бекенда (`omlx` чи `pi`) для заданого model-id.
-- `omlxHealthCheck` — preflight-стан локального сервера: `{ ok, reason, detail }`.
+pickBackend — Бекенд для model-id: `omlx` — прямий HTTP, `pi` — CLI.
+callLlm — Універсальний виклик LLM з маршрутизацією за префіксом model-id і постійне відстеження (wire-trace) обох каналів.
+omlxHealthCheck — Перевірка omlx перед масовим прогоном через мінімальний чат-виклик (`max_tokens: 1`). Розрізняє стани:
+  down — Сервер не відповідає (не запущений / не той порт).
+  memory-guard — Модель не влазить у динамічну стелю пам'яті зайнятої машини — відкладає прогін.
+  auth — Сервер вимагає API-ключ — виставляє `N_CURSOR_OMLX_KEY`.
+  error — Інша помилка API.
+Порожній контент відповіді — означає, що сервер живий і модель завантажена.
 
 ## Гарантії поведінки
 
-- Маршрутизація залежить лише від рядка моделі — жодних env-перемикачів бекенда.
-- Помилка транспорту прокидається винятком; трейс при цьому фіксує невдачу.
-- `memory-guard` означає «машина зайнята, спробуй пізніше», а не дефект моделі чи конвеєра.
+- Read-only: файл не виконує операцій запису у файлову систему.
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).
+- Не звертається до мережі.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nitra/cursor",
-  "version": "5.3.3",
+  "version": "5.3.4",
   "description": "CLI для завантаження cursor-правил (префікс n-) у локальний репозиторій",
   "keywords": [
     "cli",

package/skills/doc-files/.changes/260612-0012.md

@@ -0,0 +1,5 @@
+---
+bump: patch
+section: Added
+---
+Rust (.rs): тести extractFactsRust у docgen-extract.test.mjs — exports, tauri::command, struct/enum, markers, header, desc

package/skills/doc-files/js/docs/docgen-extract-anchors.md

@@ -1,27 +1,45 @@
 ---
 docgen:
   source: npm/skills/doc-files/js/docgen-extract-anchors.mjs
-  crc: e80e0827
+  crc: 49749e9c
+  score: 80
 ---
 
-# docgen-extract-anchors
+# docgen-extract-anchors.mjs
 
 ## Огляд
 
-Детермінований витяг «анкорів» — конкретних фрагментів коду, які модель зобов'язана згадати в документації, щоб не зісковзнути на generic-фрази. Анкори підставляються у промпти окремим блоком обов'язкового включення, а їх покриття перевіряється скорером.
+Витягує анкори з вихідного коду файлу.
+
+Витягує анкори з вихідного коду файлу.
+
+Формує плоский список анкор-токенів для перевірки покриття.
+
+Форматує анкори у компактний текст для system-промпта.
 
 ## Поведінка
 
-1. З тексту джерела збираються п'ять категорій анкорів: усі URL; експортовані константи-рядки з непорожнім значенням; маркери повідомлень про помилки виду `(rule.mdc)`; посилання на json-конфіги проєкту; code-block-приклади з провідного коментаря файлу (де автор зазвичай показує контракт).
-2. Кожна категорія дедуплікується зі збереженням порядку появи.
-3. Для промпта анкори форматуються в компактний текстовий блок з інструкціями, де саме їх згадати; якщо анкорів немає взагалі — блок не додається, щоб не вводити модель в оману «обов'язковими» полями.
+X
+Витягує анкори з вихідного коду файлу
+
+extractAnchors
+Витягує анкори з вихідного коду файлу
+
+anchorTokens
+Формує плоский список анкор-токенів для перевірки покриття
+
+anchorsToPrompt
+Форматує анкори у компактний текст для system-промпта
 
 ## Публічний API
 
-- `extractAnchors` — текст джерела → категоризовані анкори.
-- `anchorsToPrompt` — анкори → текстовий блок для system-промпта або порожній рядок.
+X — витягує анкори з вихідного коду файлу.
+extractAnchors — витягує анкори з вихідного коду файлу.
+anchorTokens — плоский список анкор-токенів, які мають з'явитися в документі.
+anchorsToPrompt — форматує анкори у компактний текст для system-промпта.
 
 ## Гарантії поведінки
 
-- Повністю детермінований і read-only; жодних LLM-викликів і мережі.
-- Працює по сирому тексту без AST: дешево і свідомо толерує надлишок (зайвий анкор — менша проблема, ніж пропущений).
+- Read-only: файл не виконує операцій запису у файлову систему.
+- За невдачі повертає значення помилки (`false`/`null`/`Err`) замість генерування винятку чи паніки.
+- Не звертається до мережі.

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

@@ -1,29 +1,39 @@
 ---
 docgen:
   source: npm/skills/doc-files/js/docgen-extract.mjs
-  crc: 26bb2901
+  crc: 1592076b
+  score: 100
 ---
 
-# docgen-extract
+# docgen-extract.mjs
 
 ## Огляд
 
-Детермінований екстрактор фактів про кодовий файл (нуль токенів): з тексту джерела збирається факт-лист, на якому конвеєр будує промпти, маркери поведінки й список заборонених до згадки внутрішніх імен.
+Файл витягує факти про конфігурацію та структуру проекту. Визначає мову та заголовок файлу. Витягує публічні експорти та імпорти з різних джерел. Витягує внутрішні та локальні символи. Документація перевіряє наявність операцій запису, обробки помилок, повернення хибних значень при невдачах, мережевих викликів, механізмів кешування та пропуск певних шляхів.
 
 ## Поведінка
 
-1. Провідний блок-коментар файлу (до першого коду) стає «наміром файлу»; з документувальних коментарів перед кожним експортом витягуються опис, параметри та опис повернення, відкидаючи беззмістовні заглушки.
-2. Збираються всі експортовані оголошення з безпосередньо передуючими їм коментарями.
-3. Імпорти класифікуються на stdlib / npm / внутрішні; імена символів, імпортованих із внутрішніх модулів, складають список internalSymbols — модель не має згадувати їх у доці, а скорер штрафує за витік.
-4. Маркери поведінки визначаються евристиками по тексту: read-only (немає запису у файлову систему), перехоплення помилок, повернення false/null при невдачі, звертання до мережі, кешування, свідомі пропуски шляхів.
-5. Для розширень поза js/mjs/ts повертається позначка unsupported — конвеєр переходить на one-shot-шлях.
+1. Витягується факт про файл.
+2. Визначається мова файлу.
+3. Витягується заголовок файлу.
+4. Витягуються публічні експорти.
+5. Витягуються імпорти, класифіковані за джерелом.
+6. Витягуються внутрішні символи, імпортовані з внутрішніх модулів.
+7. Витягуються локальні символи, неекспортовані функції.
+8. Визначаються евристичні маркери.
+    * readOnly: перевірка на наявність операцій запису.
+    * catchesErrors: перевірка на наявність обробки помилок.
+    * returnsFalsyOnFail: перевірка на повернення хибних значень при невдачах.
+    * network: перевірка на наявність мережевих викликів.
+    * caches: перевірка на наявність механізмів кешування.
+    * skips: пропуск шляхів .github, .git, node_modules, base/, ua/, .firebase.
 
 ## Публічний API
 
-- `extractFacts` — головна точка: текст джерела + шлях → факт-лист `{header, exports, imports, internalSymbols, markers}` або `{unsupported: true}`.
+extractFacts — код файлу перетворює на список фактів
 
 ## Гарантії поведінки
 
-- Повністю детермінований: однаковий вхід → однаковий факт-лист; жодних LLM-викликів і мережі.
-- Read-only: файл не виконує операцій запису у файлову систему.
-- Евристики свідомо толерують надлишок (зайвий маркер — менша проблема, ніж пропущений).
+- За невдачі повертає значення помилки (`false`/`null`/`Err`) замість генерування винятку чи паніки.
+- Кешує результати в межах одного прогону.
+- Свідомо пропускає шляхи: `.github`, `.git`, `node_modules`, `base/`, `ua/`, `.firebase`.

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

@@ -1,25 +1,35 @@
 ---
 docgen:
   source: npm/skills/doc-files/js/docgen-files-batch.mjs
-  crc: 20a14675
+  crc: 5c9b8d72
+  score: 95
 ---
 
-# docgen-files-batch
+# docgen-files-batch.mjs
 
 ## Огляд
 
-CLI-оркестратор масової генерації файлових док (`doc-files gen` / `doc-files stamp`): черга, вибір цілей, preflight локального сервера, запис док зі свіжою контрольною сумою і degraded-маркером. Уся важка робота живе тут, а не в контексті агента.
+runDocFilesGenCli
+Запускає генерацію документації для застарілих або відсутніх файлів.
+
+runDocFilesStampCli
+Перештампує frontmatter джерело та CRC у наявних документах без виклику LLM.
 
 ## Поведінка
 
-1. Дерево проєкту сканується, цілі обираються за режимом: за замовчуванням — застарілі доки; `--overwrite` — усі; `--retry-degraded` — свіжі за сумою, але з оцінкою нижче порогу. Зріз великого прогону — `--from N --limit M`.
-2. Перед генерацією — preflight локального сервера: «сервер лежить», «модель не влазить у пам'ять зайнятої машини» чи «потрібен API-ключ» зупиняють прогін одним зрозумілим повідомленням замість лавини помилок по файлах.
-3. Кожна ціль генерується локальним конвеєром; дока пишеться поряд із джерелом у `docs/` зі свіжою сумою. Якщо оцінка нижча за поріг — у frontmatter додаються оцінка й коди проблем, файл рахується як degraded.
-4. Підсумок: кількість успішних, degraded і помилкових файлів; за наявності degraded — підказка про `--retry-degraded`. Помилка хоча б одного файлу → exit-код `1`.
-5. `stamp` детерміновано перештамповує frontmatter у наявних доках без LLM (міграція док без суми), зберігаючи наявні поля якості.
+runDocFilesGenCli
+Запускає генерацію документації для застарілих/відсутніх док.
+
+runDocFilesStampCli
+Перештампує frontmatter source+crc у наявних доках без виклику LLM.
+
+## Публічний API
+
+- runDocFilesGenCli — згенерувати документацію для застарілих/відсутніх док.
+- runDocFilesStampCli — детерміновано (пере)штампувати frontmatter `source`+`crc` у наявних доках без виклику LLM. Для міграції док, які ще не мають CRC. Поля якості (`score`/`issues`) зберігаються з наявного frontmatter.
 
 ## Гарантії поведінки
 
-- Жодних хмарних викликів: збій локальної генерації стає помилкою чи degraded-маркером, а не ескалацією.
-- Доки пишуться атомарно по файлу: успішні цілі не відкочуються через подальші збої.
-- Прогін ніколи не комітить — рішення про фіксацію приймає користувач.
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).
+- За невдачі повертає значення помилки (`false`/`null`/`Err`) замість генерування винятку чи паніки.
+- Не звертається до мережі.

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`.
+- Не звертається до мережі.