@nitra/cursor 5.3.3 → 5.4.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-ignore.mjs

@@ -18,7 +18,8 @@ export const DOCGEN_IGNORE_GLOBS = Object.freeze([
   '**/demo/**',
   '**/docs/**',
   'npm/reports/**',
-  'npm/bin/**'
+  'npm/bin/**',
+  'npm/rules/k8s/js/manifests.mjs'
 ])
 
 const IGNORE_MATCHERS = DOCGEN_IGNORE_GLOBS.map(glob => picomatch(glob, { dot: true }))

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

@@ -265,8 +265,16 @@ export async function runDocFilesCheckCli(argv) {
   } else if (gitMode) {
     sources = gitChangedSources(root)
   } else {
+    // Значення прапорців виключаємо за індексом: порівняння за значенням при
+    // відсутньому `--max` (maxIdx = -1) викидало argv[0] — перший шлях губився
+    const flagValueIdxs = new Set(
+      ['--max', '--root']
+        .map(f => argv.indexOf(f))
+        .filter(i => i !== -1)
+        .map(i => i + 1)
+    )
     sources = argv
-      .filter(a => !a.startsWith('--') && a !== argv[maxIdx + 1])
+      .filter((a, i) => !a.startsWith('--') && !flagValueIdxs.has(i))
       .map(a => toRelSource(root, a))
       .filter(rel => rel && isDocCandidate(root, rel) && existsSync(join(root, rel)))
   }

package/{skills → rules}/doc-files/js/docs/docgen-crc.md

@@ -1,6 +1,6 @@
 ---
 docgen:
-  source: npm/skills/doc-files/js/docgen-crc.mjs
+  source: npm/rules/doc-files/js/docgen-crc.mjs
   crc: 54e8e12b
 ---
 

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

@@ -0,0 +1,45 @@
+---
+docgen:
+  source: npm/rules/doc-files/js/docgen-extract-anchors.mjs
+  crc: 49749e9c
+  score: 80
+---
+
+# docgen-extract-anchors.mjs
+
+## Огляд
+
+Витягує анкори з вихідного коду файлу.
+
+Витягує анкори з вихідного коду файлу.
+
+Формує плоский список анкор-токенів для перевірки покриття.
+
+Форматує анкори у компактний текст для system-промпта.
+
+## Поведінка
+
+X
+Витягує анкори з вихідного коду файлу
+
+extractAnchors
+Витягує анкори з вихідного коду файлу
+
+anchorTokens
+Формує плоский список анкор-токенів для перевірки покриття
+
+anchorsToPrompt
+Форматує анкори у компактний текст для system-промпта
+
+## Публічний API
+
+X — витягує анкори з вихідного коду файлу.
+extractAnchors — витягує анкори з вихідного коду файлу.
+anchorTokens — плоский список анкор-токенів, які мають з'явитися в документі.
+anchorsToPrompt — форматує анкори у компактний текст для system-промпта.
+
+## Гарантії поведінки
+
+- Read-only: файл не виконує операцій запису у файлову систему.
+- За невдачі повертає значення помилки (`false`/`null`/`Err`) замість генерування винятку чи паніки.
+- Не звертається до мережі.

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

@@ -0,0 +1,39 @@
+---
+docgen:
+  source: npm/rules/doc-files/js/docgen-extract.mjs
+  crc: e790ff64
+  score: 100
+---
+
+# docgen-extract.mjs
+
+## Огляд
+
+Файл витягує факти про конфігурацію та структуру проекту. Визначає мову та заголовок файлу. Витягує публічні експорти та імпорти з різних джерел. Витягує внутрішні та локальні символи. Документація перевіряє наявність операцій запису, обробки помилок, повернення хибних значень при невдачах, мережевих викликів, механізмів кешування та пропуск певних шляхів.
+
+## Поведінка
+
+1. Витягується факт про файл.
+2. Визначається мова файлу.
+3. Витягується заголовок файлу.
+4. Витягуються публічні експорти.
+5. Витягуються імпорти, класифіковані за джерелом.
+6. Витягуються внутрішні символи, імпортовані з внутрішніх модулів.
+7. Витягуються локальні символи, неекспортовані функції.
+8. Визначаються евристичні маркери.
+    * readOnly: перевірка на наявність операцій запису.
+    * catchesErrors: перевірка на наявність обробки помилок.
+    * returnsFalsyOnFail: перевірка на повернення хибних значень при невдачах.
+    * network: перевірка на наявність мережевих викликів.
+    * caches: перевірка на наявність механізмів кешування.
+    * skips: пропуск шляхів .github, .git, node_modules, base/, ua/, .firebase.
+
+## Публічний API
+
+extractFacts — код файлу перетворює на список фактів
+
+## Гарантії поведінки
+
+- За невдачі повертає значення помилки (`false`/`null`/`Err`) замість генерування винятку чи паніки.
+- Кешує результати в межах одного прогону.
+- Свідомо пропускає шляхи: `.github`, `.git`, `node_modules`, `base/`, `ua/`, `.firebase`.