@nitra/cursor 5.3.4 → 6.0.0

package/rules/changelog/docs/fix.md

@@ -1,183 +1,39 @@
 ---
 docgen:
   source: npm/rules/changelog/fix.mjs
-  crc: 12fc1644
+  crc: 38cf876b
+  score: 100
 ---
 
-# fix.mjs — точка входу правила `changelog`
+# fix.mjs
 
 ## Огляд
 
-Файл `npm/rules/changelog/fix.mjs` — тонкий **entry-point** для правила `changelog` у складі пакета `@nitra/cursor`. Він виконує дві ролі одночасно:
+Виконує застосування JS-занепокоєних на наданому контексті прогону. Застосовує визначену політику та генерує посилання MDC. Повертає результат прогону.
 
-1. **Library mode** — експортує функцію `run(ctx)`, яку викликає зовнішній CLI-оркестратор (`scripts/cli/fix.mjs` або аналог), коли користувач запускає `npx @nitra/cursor fix changelog` (чи прогін усіх правил `fix`). У цьому режимі `runStandardRule` отримує контекст із кешем обходу файлової системи (`walkCache`), shared summary тощо.
-2. **Standalone mode** — якщо файл запущено напряму (`bun npm/rules/changelog/fix.mjs`), виконується повноцінний CLI-сценарій із завантаженням конфігу, whitelist-фільтрацією й friendly summary — тобто еквівалент `npx @nitra/cursor fix changelog`.
+## Поведінка
 
-Сам файл **не містить бізнес-логіки** правила: вся перевірка/автофікс ділиться між суб-модулями (`applies` → `JS-concerns` → `policy` → `mdc-refs`), які підтягуються конвенційно через `runStandardRule(import.meta.dirname, ctx)`. Поведінка повністю детермінована директорією, в якій лежить `fix.mjs` (`import.meta.dirname` вказує на `npm/rules/changelog/`).
+1. Запуск правила.
+    *   Приймає контекст прогону.
+    *   Виконує застосування JS-занепокоєних.
+    *   Застосовує політику.
+    *   Генерує посилання MDC.
+    *   Повертає результат прогону.
+2. Виконання у режимі CLI.
+    *   Виконується як окремий скрипт.
+    *   Еквівалент команди `npx @nitra/cursor fix <id>`.
+    *   Виконує завантаження конфігурації.
+    *   Виконує перевірку дозволених елементів.
+    *   Генерує зведену інформацію.
+    *   Виконує повний еквівалент `fix.mjs`.
 
-Це шаблонний файл-обгортка — він повторюється для **кожного** правила в `npm/rules/<rule-id>/fix.mjs`. Зміни тут зазвичай небажані; натомість конкретна перевірка живе у сусідніх теках (`js/`, `lib/`, `meta.json`, `changelog.mdc`).
+## Публічний API
 
-## Експорти / API
+run — запускає правило: applies → JS-concerns → policy → mdc-refs (через runStandardRule).
+Library mode — викликається CLI orchestration через `import + run`.
 
-| Експорт | Тип                                               | Призначення                                                                                       |
-| ------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
-| `run`   | `function (ctx?: RuleContext) => Promise<number>` | Library-функція для виклику з зовнішнього CLI; повертає exit-code `0` (OK) або `1` (є порушення). |
+## Гарантії поведінки
 
-Сторонніх іменованих експортів немає. Default export відсутній.
-
-### Side-effect при імпорті
-
-Файл містить **top-level умовний блок**:
-
-```js
-if (isRunAsCli(import.meta.url)) {
-  process.exit(await runRuleCli(import.meta.dirname))
-}
-```
-
-— якщо модуль виконується як точка входу процесу (`process.argv[1]` відповідає `import.meta.url`), він **завершить процес** через `process.exit(...)`. У звичайному library-імпорті (`import { run } from '.../fix.mjs'`) `isRunAsCli` повертає `false`, отже `process.exit` НЕ викликається — імпорт безпечний.
-
-Зверніть увагу на `await` на top-level — файл потребує підтримки top-level await (ESM, Node ≥ 14.8 / Bun).
-
-## Функції
-
-### `run(ctx)`
-
-```js
-/**
- *
- */
-export function run(ctx) {
-  return runStandardRule(import.meta.dirname, ctx)
-}
-```
-
-- **Сигнатура:** `run(ctx?: RuleContext): Promise<number>`
-- **Параметри:**
-  - `ctx` _(optional)_ — об'єкт `RuleContext`, тип якого імпортується з `../../scripts/lib/run-standard-rule.mjs`. Зазвичай несе спільний стан між кількома правилами: кеш обходу файлів (`walkCache`), accumulator для summary, прапорці dry-run/auto-fix тощо. Якщо `ctx` не передано — `runStandardRule` створить дефолтний контекст всередині.
-- **Повертає:** `Promise<number>` — exit-code правила:
-  - `0` — порушень немає (або всі автоматично виправлені);
-  - `1` — є невиправні порушення / помилки.
-- **Side effects:**
-  - Делегує всю роботу до `runStandardRule(dir, ctx)`. Це може включати: обхід файлової системи (`walkdir`), читання/запис файлів-учасників правила (auto-fix), вивід у `stdout`/`stderr` через спільний логер, мутацію `ctx.walkCache` тощо.
-  - **Не** викликає `process.exit` напряму.
-- **Помилки:** будь-який reject від `runStandardRule` пробрасується нагору (caller відповідає за `try/catch`).
-
-### Анонімний CLI-блок (top-level)
-
-```js
-if (isRunAsCli(import.meta.url)) {
-  process.exit(await runRuleCli(import.meta.dirname))
-}
-```
-
-- **Тригер:** виконується **лише** коли файл — точка входу процесу. Використовує `isRunAsCli(import.meta.url)` для надійного визначення (порівняння `import.meta.url` з `process.argv[1]` через `pathToFileURL`).
-- **Дія:** делегує до `runRuleCli(import.meta.dirname)` — повноцінного CLI-обгортача, який:
-  - завантажує конфіг (`.cursor/cursor.json` чи аналог);
-  - застосовує whitelist/blacklist;
-  - збирає friendly summary;
-  - запускає `runStandardRule` всередині.
-- **Завершення:** `process.exit(<exit-code>)` — пробрасує код у shell для CI/IDE-інтеграцій.
-- **ESLint disables:**
-  - `n/no-process-exit` та `unicorn/no-process-exit` свідомо вимкнено коментарем — standalone entry-point **зобов'язаний** повертати exit-code для CI/IDE.
-
-## Залежності
-
-### Внутрішні (relative imports)
-
-| Модуль                                    | Що використано             | Призначення                                                                                                                                                                        |
-| ----------------------------------------- | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `../../scripts/lib/run-rule-cli.mjs`      | `isRunAsCli`, `runRuleCli` | Хелпери standalone-режиму: детект "запущено як CLI" та повноцінна CLI-обгортка.                                                                                                    |
-| `../../scripts/lib/run-standard-rule.mjs` | `runStandardRule`          | Універсальний раннер, що виконує "стандартну" послідовність етапів правила: `applies → JS-concerns → policy → mdc-refs`. Також експортує тип `RuleContext` (через JSDoc-`import`). |
-
-Шлях `../../` веде з `npm/rules/changelog/` до `npm/scripts/lib/`.
-
-### Сусідні артефакти правила `changelog`
-
-Не імпортуються напряму з цього файлу, але **використовуються `runStandardRule`** конвенційно (за іменами файлів у тій самій теці):
-
-- `npm/rules/changelog/meta.json` — метадані правила (id, опис, теги, прапорці `worktree`/`policy`).
-- `npm/rules/changelog/changelog.mdc` — людинозрозумілий зміст правила (Cursor MDC).
-- `npm/rules/changelog/js/` — JS-concerns (перевірки/фікси для коду).
-- `npm/rules/changelog/lib/` — допоміжні модулі правила.
-
-### Зовнішні (Node/runtime)
-
-- `import.meta.url` — стандарт ESM, для детекту CLI-режиму.
-- `import.meta.dirname` — потребує Node ≥ 20.11 або Bun (Bun підтримує). Передається в обидва раннери як корінь правила.
-- `process.exit` — глобал Node/Bun.
-- Top-level `await` — ESM-фіча, потребує сумісного runtime.
-
-## Потік виконання / Використання
-
-### Library mode (типовий — виклик з оркестратора `fix`)
-
-```text
-npx @nitra/cursor fix
-      │
-      ▼
-scripts/cli/fix.mjs (orchestrator)
-      │  для кожного правила з whitelist:
-      ▼
-import { run } from 'npm/rules/<id>/fix.mjs'
-      │
-      ▼
-run(ctx)
-      │
-      ▼
-runStandardRule(import.meta.dirname, ctx)
-      │
-      ▼
-applies → JS-concerns → policy → mdc-refs
-      │
-      ▼
-Promise<0 | 1>
-```
-
-Приклад програмного виклику:
-
-```js
-import { run } from '@nitra/cursor/npm/rules/changelog/fix.mjs'
-
-const code = await run({ walkCache: new Map(), summary: [] })
-if (code !== 0) {
-  // є порушення — обробити в caller
-}
-```
-
-### Standalone mode (ручний запуск/debug)
-
-```bash
-bun npm/rules/changelog/fix.mjs
-# еквівалент:
-npx @nitra/cursor fix changelog
-```
-
-Послідовність:
-
-1. ESM-модуль завантажується як entry-point.
-2. Виконуються імпорти.
-3. Експорт `run` реєструється (але ніхто не викликає).
-4. Виконується умова `isRunAsCli(import.meta.url)` → `true`.
-5. `await runRuleCli(import.meta.dirname)` — завантажує конфіг, фільтрує whitelist (тут — лише поточне правило, бо `dirname` фіксує id), запускає `runStandardRule`, друкує summary.
-6. `process.exit(<code>)` — повертає exit-code у shell.
-
-### Чому два режими в одному файлі?
-
-- **DRY** — не дублювати entry-point на кожне правило.
-- **DevEx** — розробник може дебажити одне правило: `bun npm/rules/<id>/fix.mjs`.
-- **CI** — оркестратор `fix.mjs` імпортує `run` гуртом, ділить кеш обходу між правилами для прискорення.
-
-## Rebuild Test (контекстна незалежність)
-
-Файл можна відтворити, маючи лише цю документацію:
-
-1. Створіть `npm/rules/changelog/fix.mjs`.
-2. Імпортуйте `isRunAsCli` та `runRuleCli` з `../../scripts/lib/run-rule-cli.mjs`.
-3. Імпортуйте `runStandardRule` з `../../scripts/lib/run-standard-rule.mjs`.
-4. Експортуйте функцію `run(ctx)`, яка повертає результат `runStandardRule(import.meta.dirname, ctx)`.
-5. Додайте JSDoc до `run` з типом `RuleContext` (через `import('../../scripts/lib/run-standard-rule.mjs').RuleContext`) і `Promise<number>` на повернення.
-6. Внизу додайте умовний блок `if (isRunAsCli(import.meta.url)) { process.exit(await runRuleCli(import.meta.dirname)) }`.
-7. Поряд із `process.exit(...)` додайте eslint-disable коментар для `n/no-process-exit` та `unicorn/no-process-exit` із обґрунтуванням "standalone entry-point має повертати exit-code для CI/IDE".
-
-Результат має бути ідентичним за поведінкою оригіналу: library-імпорт безпечний, standalone-запуск завершує процес коректним exit-code.
+- Read-only: файл не виконує операцій запису у файлову систему.
+- Кешує результати в межах одного прогону.
+- Не звертається до мережі.

package/rules/ci4/docs/fix.md

@@ -1,7 +1,7 @@
 ---
 docgen:
   source: npm/rules/ci4/fix.mjs
-  crc: 12fc1644
+  crc: 38cf876b
   score: 100
 ---
 
@@ -9,26 +9,23 @@ docgen:
 
 ## Огляд
 
-Модуль виконує бізнес-процес трансформації даних. Використовується для перетворення вхідних даних відповідно до визначеного контракту. Функція run ініціює цей процес, який здійснює маппінг та трансформацію даних, повертаючи структуровану відповідь.
+Огляд
+Файл надає функціонал для виконання визначених правил. Публічні методи забезпечують запуск цих правил, повертаючи отримані результати. Дозволяє запускати правила у режимі командного рядка, керуючи виходом процесу на основі отриманих даних.
 
 ## Поведінка
 
-1. Виклик функції run передає контекст прогону для виконання правила.
+1. Запуск правила.
+    *   Виклик runStandardRule з контекстом.
+    *   Повернення результату.
 
-2. Виконання правила відбувається через стандартний механізм перевірки.
-
-3. У режимі бібліотеки функція викликає основну логіку перевірки, яка включає застосування правил, перевірку конфігурації та формування посилань.
-
-4. Якщо виконання відбувається у режимі командного рядка, функція виконує повний еквівалент інструментального прогону.
-
-5. У режимі командного рядка функція виконує команду, яка включає завантаження конфігурації, перевірку дозволених елементів та формування зведення.
-
-6. У режимі командного рядка результат виконання передається для негайного завершення процесу, що використовується для інструментальних середовищ.
+2. Запуск правила у режимі CLI.
+    *   Виклик runRuleCli з директорією модуля.
+    *   Вихід з процесом залежно від результату.
 
 ## Публічний API
 
-run — Запускає послідовність перевірок: applies до mdc-refs через policy та JS-concerns.
-Library mode — Викликається через CLI оркестрацію за допомогою імпорту та функції run.
+run — запускає правило: applies → JS-concerns → policy → mdc-refs (через runStandardRule).
+Library mode — викликається CLI orchestration через `import + run`.
 
 ## Гарантії поведінки
 

package/rules/doc-files/doc-files.mdc

@@ -0,0 +1,60 @@
+---
+description: Файлова документація — обовʼязковий крок задачі (як lint); детермінований детектор застарілості за CRC джерела (lint-doc-files), генерація local-only конвеєром (fix-doc-files)
+globs: "**/*.{js,mjs,ts,vue,py,rs},**/docs/**"
+alwaysApply: true
+version: '1.0'
+---
+
+Кожен кодовий файл (`.js .mjs .ts .vue .py .rs`, крім тестів і `.d.ts`) має **актуальну**
+файлову доку поряд: `<dir>/docs/<stem>.md`. Це **обовʼязковий крок кожної задачі**, нарівні
+з lint. Актуальність детермінується за **CRC** джерела, записаним у frontmatter доки.
+
+## Дві відповідальності — дві команди
+
+- **`lint-doc-files`** — детермінований **детектор**: знаходить кодові файли без актуальної
+  доки. **0 викликів LLM**, працює локально, в hook'ах і в CI.
+- **`fix-doc-files`** — **генератор**: створює/оновлює доки local-only конвеєром (omlx) зі
+  штампом CRC. Потребує локальної моделі; у CI **не** запускається.
+
+Це та сама пара, що `/n-lint` (детект) проти `/n-fix` (закриття) у решті проєкту.
+
+## Stale = `missing` ∪ `crc-mismatch`
+
+Дока застаріла, якщо її **немає** (`missing`) або `crc(джерело) ≠ crc` у frontmatter
+(`crc-mismatch`). **Degraded** (низький score, але CRC свіжий) — **не** stale; це борг, видимий
+через `lint-doc-files --degraded` і закривається `fix-doc-files --retry-degraded`.
+
+Алгоритм детекту (кандидати, ignore-дерево, CRC, реверс-мапінг доки→джерело) повністю в
+`js/docgen-scan.mjs` / `js/docgen-crc.mjs` / `js/docgen-ignore.mjs` і адаптері `js/lint.mjs`;
+тут — лише людинозрозумілий контракт, без дублювання логіки.
+
+## Мапа команд
+
+| Команда | Exit | Семантика |
+| --- | --- | --- |
+| `lint-doc-files` | 1 — є stale | повний детект, людиночитний список stale |
+| `lint-doc-files [paths…]` | 1 | точковий детект заданих джерел |
+| `lint-doc-files --missing-only` | 1 | лише `missing`, без `crc-mismatch` |
+| `lint-doc-files --json` | 0 | JSON-лістинг усіх кандидатів зі станом |
+| `lint-doc-files --hook` | 2 — stale | PostToolUse: stdin JSON, один файл |
+| `lint-doc-files --git [--max N]` | 2 — stale | Stop-гейт: `git diff` HEAD; понад поріг (`N_CURSOR_DOC_FILES_GATE_MAX`, дефолт 50) — warn + exit 0 |
+| `lint-doc-files --degraded` | 0 | звіт про доки зі score < порогу |
+| `fix-doc-files [--limit/--from/--overwrite/--retry-degraded]` | 0/1 | local-only генерація зі штампом CRC |
+| `fix-doc-files --stamp` | 0/1 | детерміноване перештампування `source`+`crc` без LLM |
+
+Exit-коди: повний прогін — **1** (конвенція `lint-*`); `--hook`/`--git` — **2** (hook-протокол
+Claude Code: blocking feedback).
+
+## Hook'и
+
+PostToolUse (`lint-doc-files --hook`) **сигналить** про дрейф після правки кодового файлу;
+Stop-гейт (`lint-doc-files --git`) **блокує завершення** задачі за наявності застарілих док
+(виняток — масовий прогін понад поріг). Регенерація — `/doc-files` (JS-оркестрована, не диспатч
+субагентів). Агрегуюча дока (module-summary, доменні) — окремий скіл `/doc-aggregate`.
+
+## Серіалізація
+
+Повний `lint-doc-files` і `fix-doc-files` серіалізуються через `runStandardLint` /
+`runStandardRule` (ключі `lint-doc-files` / `fix-doc-files`, виводяться зі шляху каталогу).
+`--hook` / `--git` — окрема форма **без локу** (швидкий точковий вердикт). Деталі —
+`.cursor/rules/scripts.mdc`, секція «Серіалізація важких CLI-команд».

package/rules/doc-files/docs/fix.md

@@ -0,0 +1,31 @@
+---
+docgen:
+  source: npm/rules/doc-files/fix.mjs
+  crc: 9df3e88d
+  score: 100
+---
+
+# fix.mjs
+
+## Огляд
+
+Точка входу правила doc-files для каналу `n-cursor fix doc-files`. Перевіряє структурні вимоги
+правила (наявність потрібного GA-workflow і скрипта в `package.json` через policy-канал), не
+чіпаючи вміст самих док.
+
+## Поведінка
+
+Делегує стандартному оркестратору правил: applies → JS-concerns → policy → перевірка
+markdown-посилань. Контентні порушення (відсутні чи застарілі файлові доки) свідомо поза цим
+каналом — їх закриває окрема команда генерації `fix-doc-files`, а не загальний `fix`.
+
+## Публічний API
+
+`run` — виконує перевірку правила і повертає код виходу (`0` — без зауважень, `1` — є порушення).
+При прямому запуску файлу працює як повний еквівалент `npx @nitra/cursor fix doc-files` із
+завантаженням конфігу та підсумком.
+
+## Гарантії поведінки
+
+- Серіалізується спільним локом, тож паралельні запуски того самого правила дедуплікуються.
+- Не виконує генерацію документації — лише структурну перевірку.

package/rules/doc-files/fix.mjs

@@ -0,0 +1,19 @@
+import { isRunAsCli, runRuleCli } from '../../scripts/lib/run-rule-cli.mjs'
+import { runStandardRule } from '../../scripts/lib/run-standard-rule.mjs'
+
+/**
+ * Запускає правило doc-files: applies → JS-concerns → policy → mdc-refs (через runStandardRule).
+ * Структурні concerns (наявність workflow lint-doc-files.yml, скрипт у package.json) закриває
+ * policy-канал; контентні порушення (відсутні/застарілі доки) — поза `n-cursor fix`, їх закриває
+ * `fix-doc-files` (генерація). Library mode: викликається через `import + run(ctx)`.
+ * @param {import('../../scripts/lib/run-standard-rule.mjs').RuleContext} [ctx] контекст прогону
+ * @returns {Promise<number>} 0 — OK, 1 — порушення
+ */
+export function run(ctx) {
+  return runStandardRule(import.meta.dirname, ctx)
+}
+
+if (isRunAsCli(import.meta.url)) {
+  // Standalone: bun rules/doc-files/fix.mjs — еквівалент `npx @nitra/cursor fix doc-files`.
+  process.exitCode = await runRuleCli(import.meta.dirname)
+}

package/{skills → rules}/doc-files/js/docgen-extract.mjs

@@ -213,26 +213,32 @@ function extractMarkers(src) {
 
 // ── Rust-екстрактор ──────────────────────────────────────────────────────────
 
-// Модульний //! doc-коментар (inner doc)
-const RS_MODULE_DOC_RE = /^(?:[ \t]*\/\/![ \t]?(.*)\n)*/m
-
 // pub fn / pub struct / pub enum / pub trait (та fn із exposure-атрибутом)
-const RS_PUB_ITEM_RE = /^[ \t]*(pub(?:\([^)]*\))?\s+)?(?:async\s+)?(?:unsafe\s+)?(fn|struct|enum|trait|type)\s+(\w+)/gm
+// матчаться у два кроки по trim-нутому рядку — прості регекспи без бектрекінгу:
+// спершу опційний pub(...)-префікс, потім сама декларація
+const RS_PUB_PREFIX_RE = /^pub(?:\([^)]*\))?\s+/
+const RS_ITEM_DECL_RE = /^(?:async\s+)?(?:unsafe\s+)?(fn|struct|enum|trait|type)\s+(\w+)/
+
+// fn-декларація у trim-нутому рядку одразу після exposure-атрибута
+const RS_FN_AFTER_ATTR_RE = /^(?:pub\s+)?(?:async\s+)?(?:unsafe\s+)?fn\s+/
+
+// Будь-яка fn-декларація без pub (для приватних localSymbols)
+const RS_PRIVATE_FN_RE = /^[ \t]*(?:async\s+)?(?:unsafe\s+)?fn\s+(\w+)/
 
 // Exposure-атрибути (#[tauri::command] тощо)
 const RS_EXPOSURE_ATTR_RE = /#\[(?:tauri::command|wasm_bindgen|uniffi::export|pyo3::pyfunction|napi)/gm
 
-// /// line-doc перед елементом
-const RS_LINE_DOC_RE = /(?:[ \t]*\/\/\/[ \t]?.*\n)*/
-
 // use crate::module::{A, B}  або  use std::..;
 const RS_USE_RE = /^[ \t]*use\s+([\w:]+(?:::\{[^}]+\})?(?:::\*)?(?:::\w+)?)\s*;/gm
 
 // Файловий запис: fs::write / File::create / remove_file / create_dir / write_all
 const RS_WRITE_RE = /fs::write|File::create|remove_file|create_dir|BufWriter::new|OpenOptions[^;]*\.write\s*\(\s*true/
 
-// Обробка помилок (але не просто `?`)
-const RS_CATCH_RE = /\.unwrap_or(?:_else|_default)?|if\s+let\s+Err\s*\(|match\s+\S+.*\{\s*[\s\S]*?Err\s*\(|\.map_err\s*\(|\.ok\s*\(\)/
+// Обробка помилок (але не просто `?`): прості маркери; випадок
+// «match … з Err(-гілкою» — віконним обходом рядків у rsHasMatchWithErrArm
+const RS_CATCH_SIMPLE_RES = [/\.unwrap_or(?:_else|_default)?/, /if\s+let\s+Err\s*\(/, /\.map_err\s*\(/, /\.ok\s*\(\)/]
+const RS_MATCH_KW_RE = /\bmatch\s/
+const RS_ERR_ARM_RE = /\bErr\s*\(/
 
 // Функції, що повертають Result або Option
 const RS_RESULT_RE = /->\s*(?:Result|Option)\s*</
@@ -243,6 +249,21 @@ const RS_NETWORK_RE = /reqwest|hyper::|TcpStream|UdpSocket|tokio::net/
 // Кешування
 const RS_CACHE_RE = /\bcache\b|\bCache\b|lazy_static!|OnceCell|OnceLock|DashMap/i
 
+/**
+ * Чи містить джерело `match`-вираз із `Err(`-гілкою неподалік (вікно 12 рядків).
+ * Замінює бектрекінг-вразливу регулярку детермінованим обходом рядків.
+ * @param {string[]} srcLines рядки файлу
+ * @returns {boolean} true, якщо за `match` слідує `Err(`
+ */
+function rsHasMatchWithErrArm(srcLines) {
+  for (let i = 0; i < srcLines.length; i++) {
+    if (!RS_MATCH_KW_RE.test(srcLines[i])) continue
+    const end = Math.min(i + 12, srcLines.length)
+    for (let j = i; j < end; j++) if (RS_ERR_ARM_RE.test(srcLines[j])) return true
+  }
+  return false
+}
+
 /**
  * Видобуває `///` doc-рядки перед рядком `lineIdx` (назад через `#[...]` та пусті рядки).
  * @param {string[]} lines рядки файлу
@@ -254,8 +275,9 @@ function rsDocBefore(lines, lineIdx) {
   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 === '') { /* skip */ }
-    else break
+    else if (t.startsWith('#[') || t.startsWith('#![') || t === '') {
+      /* skip */
+    } else break
   }
   return doc.join(' ').trim()
 }
@@ -289,7 +311,7 @@ function extractFactsRust(src, relPath) {
         for (let nli = li + 1; nli < Math.min(li + 5, srcLines.length); nli++) {
           const t = srcLines[nli].trim()
           if (t.startsWith('#[') || t === '') continue
-          if (/^(?:pub\s+)?(?:async\s+)?(?:unsafe\s+)?fn\s+/.test(t)) exposedLineSet.add(nli)
+          if (RS_FN_AFTER_ATTR_RE.test(t)) exposedLineSet.add(nli)
           break
         }
         break
@@ -303,12 +325,14 @@ function extractFactsRust(src, relPath) {
   let lineOffset = 0
   for (let li = 0; li < srcLines.length; li++) {
     const line = srcLines[li]
-    const m = line.match(/^[ \t]*(pub(?:\([^)]*\))?\s+)?(?:async\s+)?(?:unsafe\s+)?(fn|struct|enum|trait|type)\s+(\w+)/)
+    const trimmed = line.trimStart()
+    const pubM = trimmed.match(RS_PUB_PREFIX_RE)
+    const m = (pubM ? trimmed.slice(pubM[0].length) : trimmed).match(RS_ITEM_DECL_RE)
     if (m) {
-      const isPub = Boolean(m[1]) || exposedLineSet.has(li)
+      const isPub = Boolean(pubM) || exposedLineSet.has(li)
       if (isPub) {
         const desc = rsDocBefore(srcLines, li)
-        exports.push({ name: m[3], kind: m[2], desc })
+        exports.push({ name: m[2], kind: m[1], desc })
       }
     }
     lineOffset += line.length + 1
@@ -316,9 +340,8 @@ function extractFactsRust(src, relPath) {
 
   // localSymbols — приватні fn (не pub і не exposed) — не документуємо як публічний API
   const localSymbols = []
-  for (let li = 0; li < srcLines.length; li++) {
-    const line = srcLines[li]
-    const m = line.match(/^[ \t]*(?:async\s+)?(?:unsafe\s+)?fn\s+(\w+)/)
+  for (const line of srcLines) {
+    const m = line.match(RS_PRIVATE_FN_RE)
     if (m && !exports.some(e => e.name === m[1])) localSymbols.push(m[1])
   }
 
@@ -336,7 +359,7 @@ function extractFactsRust(src, relPath) {
   // markers
   const markers = {
     readOnly: !RS_WRITE_RE.test(src),
-    catchesErrors: RS_CATCH_RE.test(src),
+    catchesErrors: RS_CATCH_SIMPLE_RES.some(re => re.test(src)) || rsHasMatchWithErrArm(srcLines),
     returnsFalsyOnFail: RS_RESULT_RE.test(src),
     network: RS_NETWORK_RE.test(src),
     caches: RS_CACHE_RE.test(src),

package/{skills → rules}/doc-files/js/docgen-files-batch.mjs

@@ -90,6 +90,19 @@ function modeSuffix({ overwrite, retryDegraded }) {
   return ''
 }
 
+/**
+ * Рядок таймінгу одного файлу: загальний час, час у LLM (і кількість викликів)
+ * та залишок — оркестрація (екстракт фактів, скоринг, парсинг, IO). Дає зрозуміти,
+ * скільки коштує сама модель проти JS-оркестрації.
+ * @param {{ ms: number, llmMs?: number, llmCalls?: number }} r результат generateDoc
+ * @returns {string} напр. `12.3s (llm 11.8s/7 calls, orch 0.5s)`
+ */
+function fmtTiming(r) {
+  const s = ms => `${(ms / 1000).toFixed(1)}s`
+  const llmMs = r.llmMs ?? 0
+  return `${s(r.ms)} (llm ${s(llmMs)}/${r.llmCalls ?? 0} calls, orch ${s(r.ms - llmMs)})`
+}
+
 /**
  * Генерує й штампує доку для одного файлу, оновлюючи лічильники й прогрес.
  * @param {object} file елемент scanForDocFiles
@@ -114,9 +127,9 @@ async function generateOne(file, root, progress, stats) {
     stats.ok++
     if (result.degraded) {
       stats.degraded++
-      process.stdout.write(`⚠ degraded score=${result.score} crc=${crc}\n`)
+      process.stdout.write(`⚠ degraded score=${result.score} crc=${crc}  ${fmtTiming(result)}\n`)
     } else {
-      process.stdout.write(`✓ score=${result.score ?? '—'} crc=${crc}\n`)
+      process.stdout.write(`✓ score=${result.score ?? '—'} crc=${crc}  ${fmtTiming(result)}\n`)
     }
   } catch (error) {
     stats.err++
@@ -137,7 +150,7 @@ function reportStats(stats) {
     for (const e of stats.errors) console.log(`  - ${e}`)
   }
   if (stats.degraded > 0) {
-    console.log(`Degraded-доки перегенеровуються пізніше: npx @nitra/cursor doc-files gen --retry-degraded`)
+    console.log(`Degraded-доки перегенеровуються пізніше: npx @nitra/cursor fix-doc-files --retry-degraded`)
   }
 }
 
@@ -164,7 +177,7 @@ export async function runDocFilesGenCli(argv) {
 
   const problem = preflightProblem()
   if (problem) {
-    console.error(`✗ doc-files gen: ${problem}`)
+    console.error(`✗ fix-doc-files: ${problem}`)
     return 1
   }
 
@@ -201,7 +214,7 @@ export function runDocFilesStampCli(argv) {
     writeFileSync(docAbs, stampDoc(md, file.sourcePath, crc, score === null ? null : { score, issues }))
     stamped++
   }
-  console.log(`✓ doc-files stamp: оновлено frontmatter у ${stamped} доці(ах).`)
+  console.log(`✓ fix-doc-files --stamp: оновлено frontmatter у ${stamped} доці(ах).`)
   return 0
 }
 

package/{skills → rules}/doc-files/js/docgen-gen.mjs

@@ -4,7 +4,7 @@ import { basename } from 'node:path'
 import { env } from 'node:process'
 import { resolveModel } from '../../../lib/models.mjs'
 import { DEFAULT_OMLX_MODEL } from '../../../lib/omlx.mjs'
-import { callLlm } from '../../../lib/llm.mjs'
+import { callLlm as callLlmRaw } from '../../../lib/llm.mjs'
 import { isRunAsCli } from '../../../scripts/cli-entry.mjs'
 import { docPathForSource } from './docgen-scan.mjs'
 import { extractFacts } from './docgen-extract.mjs'
@@ -19,6 +19,26 @@ import {
   guaranteesFromMarkers
 } from './docgen-prompts.mjs'
 
+/** Облік LLM-викликів і часу в них у межах однієї генерації (скидається на старті generateDoc). */
+let llmMeter = { calls: 0, ms: 0 }
+
+/**
+ * Обгортка callLlm з обліком: лічить кількість викликів і сумарний час у них.
+ * callLlm синхронний (spawnSync/curl), генерація одного файлу послідовна — лічильник без гонок.
+ * Усі виклики `callLlm(...)` у цьому модулі йдуть через неї автоматично (імпорт як callLlmRaw).
+ * @param {...any} args ті самі аргументи, що й у callLlm з lib/llm.mjs
+ * @returns {string} відповідь моделі
+ */
+function callLlm(...args) {
+  const started = Date.now()
+  try {
+    return callLlmRaw(...args)
+  } finally {
+    llmMeter.calls += 1
+    llmMeter.ms += Date.now() - started
+  }
+}
+
 const FENCE_OPEN_RE = /^```[a-z]*\n?/
 const FENCE_CLOSE_RE = /\n?```\s*$/
 const LEADING_HEADING_RE = /^#{1,6}[ \t]{1,8}[^\n]{0,400}\n{1,8}/
@@ -360,12 +380,13 @@ export const DEFAULT_LOCAL_MODEL = env.N_CURSOR_DOCGEN_MODEL ?? (resolveModel('m
  * позначається `degraded`, рішення про перегенерацію приймає batch/користувач.
  * @param {string} file абсолютний шлях джерела
  * @param {{ model?: string, threshold?: number, existingMd?: string|null }} [opts] model-id, поріг degraded, наявна дока (для збереження захищеної секції)
- * @returns {{ md: string, ms: number, score: number|null, issues: string[], degraded: boolean, model: string }} документ і метадані генерації
+ * @returns {{ md: string, ms: number, llmMs: number, llmCalls: number, score: number|null, issues: string[], degraded: boolean, model: string }} документ і метадані генерації (ms — увесь файл; llmMs/llmCalls — лише LLM; решта ms — оркестрація)
  */
 export function generateDoc(file, { model = DEFAULT_LOCAL_MODEL, threshold = QUALITY_THRESHOLD, existingMd = null } = {}) {
   const src = readFileSync(file, 'utf8')
   const facts = extractFacts(src, file)
   const t0 = Date.now()
+  llmMeter = { calls: 0, ms: 0 }
 
   // Варіант B: захищена секція «Призначення» з наявної доки — зберегти й подати як контекст
   const intent = existingMd ? splitProtected(existingMd).body : null
@@ -376,7 +397,16 @@ export function generateDoc(file, { model = DEFAULT_LOCAL_MODEL, threshold = QUA
 
   // unsupported (vue/py до юніт-шару): скорер не застосовний — score=null, не degraded
   if (facts.unsupported) {
-    return { ...r, ms: Date.now() - t0, score: null, issues: [], degraded: false, model }
+    return {
+      ...r,
+      ms: Date.now() - t0,
+      llmMs: llmMeter.ms,
+      llmCalls: llmMeter.calls,
+      score: null,
+      issues: [],
+      degraded: false,
+      model
+    }
   }
 
   // Stage 2.5: детермінований скоринг (0 токенів)
@@ -399,7 +429,16 @@ export function generateDoc(file, { model = DEFAULT_LOCAL_MODEL, threshold = QUA
     }
   }
 
-  return { ...r, ms: Date.now() - t0, score, issues, degraded: score < threshold, model }
+  return {
+    ...r,
+    ms: Date.now() - t0,
+    llmMs: llmMeter.ms,
+    llmCalls: llmMeter.calls,
+    score,
+    issues,
+    degraded: score < threshold,
+    model
+  }
 }
 
 // CLI: node docgen-gen.mjs <file> [--model <m>]
@@ -416,6 +455,8 @@ if (isRunAsCli(import.meta.url)) {
   const existingMd = existsSync(docPath) ? readFileSync(docPath, 'utf8') : null
   const r = generateDoc(file, { model, existingMd })
   const issuesTxt = r.issues?.length ? ` issues=${r.issues.join(',')}` : ''
-  process.stderr.write(`[local ${r.model}] ${r.ms}ms / score=${r.score}${r.degraded ? ' DEGRADED' : ''}${issuesTxt}\n`)
+  process.stderr.write(
+    `[local ${r.model}] ${r.ms}ms (llm ${r.llmMs}ms/${r.llmCalls} calls, orch ${r.ms - r.llmMs}ms) / score=${r.score}${r.degraded ? ' DEGRADED' : ''}${issuesTxt}\n`
+  )
   process.stdout.write(r.md)
 }