@nitra/cursor 5.1.0 → 5.2.1

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

@@ -13,9 +13,7 @@ const SOURCE_EXTENSIONS = new Set(['.js', '.mjs', '.ts', '.vue', '.py'])
 const TEST_FILE_RE = /\.(?:test|spec)\.[^.]+$/u
 
 /**
- * Чи корінь має system-wide docs layout.
- * Такий корінь зарезервований під репозиторні docs/adr, docs/explanation тощо,
- * тому file-level docs у нього не пишемо.
+ * Чи корінь має system-wide docs layout (зарезервований під repo docs/adr тощо).
  * @param {string} root абсолютний корінь обходу
  * @returns {boolean} true — корінь system-wide docs
  */
@@ -26,7 +24,7 @@ function isSystemWideDocsRoot(root) {
 /**
  * Чи є файл кодовим джерелом для документування.
  * @param {string} fileName базове ім'я файлу
- * @returns {boolean} true — документуємо; false — пропускаємо
+ * @returns {boolean} true — документуємо
  */
 export function isSourceFile(fileName) {
   if (fileName.endsWith('.d.ts')) return false
@@ -35,30 +33,14 @@ export function isSourceFile(fileName) {
 }
 
 /**
- * Обчислює шлях md-документа для кодового файлу: тека `docs/` поряд із джерелом.
- * Якщо `sourcePath` відносний, `docPath` теж відносний; якщо абсолютний — абсолютний.
- * @param {string} sourcePath шлях до джерела (відносний або абсолютний)
- * @returns {string} шлях до `<dir>/docs/<stem>.md` у тому ж просторі шляхів
- */
-export function docPathForSource(sourcePath) {
-  const dir = path.dirname(sourcePath)
-  const stem = path.basename(sourcePath, path.extname(sourcePath))
-  return path.join(dir, 'docs', `${stem}.md`)
-}
-
-/**
- * Рекурсивно обходить дерево від `root`, повертає кодові файли для документування.
- * Синхронний `readdirSync` — детермінований порядок і простий рекурсивний обхід без
- * гонок; обсяг дерева проєкту це дозволяє.
+ * Рекурсивно збирає кодові файли проєкту (posix-шляхи від кореня).
  * @param {string} root абсолютний корінь обходу
- * @returns {Array<{sourcePath:string, docPath:string, exists:boolean}>} список кандидатів з відносними шляхами
+ * @returns {string[]} sourcePath-и
  */
-export function scanForDocgen(root) {
+export function scanSourceFiles(root) {
   const results = []
 
-  /**
-   * @param {string} dir поточний каталог обходу
-   */
+  /** @param {string} dir поточний каталог обходу */
   function walk(dir) {
     let entries
     try {
@@ -76,12 +58,7 @@ export function scanForDocgen(root) {
         if (isSystemWideDocsRoot(root) && path.dirname(relPath) === '.') continue
         const sourcePath = relPath.split(path.sep).join('/')
         if (isDocgenIgnored(sourcePath)) continue
-        const docPath = docPathForSource(sourcePath)
-        results.push({
-          sourcePath,
-          docPath,
-          exists: existsSync(path.join(root, docPath))
-        })
+        results.push(sourcePath)
       }
     }
   }
@@ -98,7 +75,6 @@ export function scanForDocgen(root) {
  */
 export function slugForModule(root, moduleRoot) {
   const rel = path.relative(root, moduleRoot)
-  // корінь репо: фіксований sentinel 'root'
   if (rel === '') return 'root'
   return rel
     .split(path.sep)
@@ -108,7 +84,6 @@ export function slugForModule(root, moduleRoot) {
 
 /**
  * Знаходить корені модулів — теки з `package.json` (корінь завжди модуль).
- * Ті ж ignore-glob правила, тож `package.json` у службових деревах не враховується.
  * @param {string} root абсолютний корінь обходу
  * @returns {string[]} абсолютні шляхи коренів модулів
  */
@@ -159,17 +134,17 @@ export function nearestModuleRoot(filePath, moduleRoots) {
  * Лістить логічні модулі проєкту з членами-файлами і docPath module-summary.
  * Модулі без кодових файлів пропускаються.
  * @param {string} root абсолютний корінь обходу
- * @returns {Array<{moduleRoot:string, relRoot:string, slug:string, docPath:string, members:string[], exists:boolean}>} модулі (members — sourcePath-и, відносні від root)
+ * @returns {Array<{moduleRoot:string, relRoot:string, slug:string, docPath:string, members:string[], exists:boolean}>} модулі (members — sourcePath-и від root)
  */
 export function scanForModules(root) {
-  const files = scanForDocgen(root)
+  const files = scanSourceFiles(root)
   const moduleRoots = findModuleRoots(root)
   const byRoot = new Map()
-  for (const file of files) {
-    const moduleRoot = nearestModuleRoot(path.join(root, file.sourcePath), moduleRoots)
+  for (const sourcePath of files) {
+    const moduleRoot = nearestModuleRoot(path.join(root, sourcePath), moduleRoots)
     if (moduleRoot === null) continue
     if (!byRoot.has(moduleRoot)) byRoot.set(moduleRoot, [])
-    byRoot.get(moduleRoot).push(file.sourcePath)
+    byRoot.get(moduleRoot).push(sourcePath)
   }
 
   const results = []
@@ -190,7 +165,7 @@ export function scanForModules(root) {
 }
 
 /**
- * Парсить `--root <dir>` з argv; default — cwd.
+ * Парсить `--root <dir>`; default — cwd.
  * @param {string[]} argv аргументи після підкоманди
  * @returns {string} абсолютний корінь
  */
@@ -200,42 +175,22 @@ export function resolveRoot(argv) {
 }
 
 /**
- * Парсить `--root <dir>` (default — cwd), сканує і друкує JSON-масив у stdout.
- * @param {string[]} argv аргументи після назви субкоманди (наприклад ['--root', '<dir>'])
- * @returns {Promise<number>} exit-код: 0 — успіх, 1 — корінь не існує
- */
-export async function runDocgenScanCli(argv) {
-  const root = resolveRoot(argv)
-
-  if (!existsSync(root) || !statSync(root).isDirectory()) {
-    console.error(`docgen scan: корінь не існує або не є директорією: ${root}`)
-    return 1
-  }
-
-  const items = await scanForDocgen(root)
-  console.log(JSON.stringify(items, null, 2))
-  return 0
-}
-
-/**
- * Парсить `--root`, сканує модулі і друкує JSON-масив у stdout.
- * @param {string[]} argv аргументи після назви субкоманди (наприклад ['--root', '<dir>'])
- * @returns {Promise<number>} exit-код: 0 — успіх, 1 — корінь не існує
+ * `doc-aggregate modules` — сканує модулі і друкує JSON-масив у stdout.
+ * @param {string[]} argv аргументи після назви субкоманди
+ * @returns {number} exit-код: 0 — успіх, 1 — корінь не існує
  */
-export async function runDocgenModulesCli(argv) {
+export function runDocAggregateModulesCli(argv) {
   const root = resolveRoot(argv)
-
   if (!existsSync(root) || !statSync(root).isDirectory()) {
-    console.error(`docgen modules: корінь не існує або не є директорією: ${root}`)
+    console.error(`doc-aggregate modules: корінь не існує або не є директорією: ${root}`)
     return 1
   }
-
-  const items = await scanForModules(root)
-  console.log(JSON.stringify(items, null, 2))
+  console.log(JSON.stringify(scanForModules(root), null, 2))
   return 0
 }
 
 if (isRunAsCli(import.meta.url)) {
-  // Прямий запуск: `node skills/docgen/js/docgen-scan.mjs --root <dir>`
-  process.exitCode = await runDocgenScanCli(process.argv.slice(2))
+  // Прямий запуск: `node skills/doc-aggregate/js/docgen-scan.mjs modules --root <dir>`
+  const [sub, ...rest] = process.argv.slice(2)
+  process.exitCode = runDocAggregateModulesCli(sub === 'modules' ? rest : process.argv.slice(2))
 }

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

@@ -0,0 +1,21 @@
+---
+docgen:
+  source: npm/skills/doc-aggregate/js/docgen-ignore.mjs
+  crc: 8821af65
+---
+
+# docgen-ignore
+
+## Огляд
+
+Re-export спільного списку ignore-глобів зі скіла doc-files: обидва скіли документації (пофайлові доки й агрегати) мусять бачити однакове дерево кодових файлів, інакше агрегат посилатиметься на файли без док або навпаки.
+
+## Поведінка
+
+1. Модуль не має власної логіки: повністю делегує канонічному джерелу в doc-files і повторно експортує його API (список глобів і перевірку належності шляху до ігнорованих).
+2. Напрям залежності — doc-aggregate → doc-files, відповідно до рішення про розбиття docgen на два скіли.
+
+## Гарантії поведінки
+
+- Списки ignore-глобів двох скілів не можуть розійтися — джерело одне.
+- Read-only, без мережі й побічних ефектів.

package/skills/doc-files/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: doc-files
+description: >-
+  Обовʼязковий крок задачі (як lint): для кожного зміненого/нового кодового файлу (js/mjs/ts/vue/py) JS-оркестрована генерація лаконічної поведінкової української md-документації у теку docs/ поряд із кодом, зі звіркою застарілості за CRC у frontmatter
+---
+
+# doc-files — файлова документація (обовʼязковий крок)
+
+## Мета
+
+Для кожного кодового файлу проєкту тримати **актуальну** лаконічну поведінкову `.md`-документацію
+у теці `docs/` **поряд із самим файлом** (`<dir>/docs/<stem>.md`). Це **обовʼязковий крок кожної
+задачі** — як `lint`: після зміни коду його дока має бути перегенерована.
+
+Застарілість визначається **детерміновано за CRC**: кожна дока несе у frontmatter контрольну
+суму байтів джерела на момент генерації. Дока **застаріла**, якщо її немає або
+`crc(поточне джерело) ≠ crc у frontmatter`.
+
+```markdown
+---
+docgen:
+  source: src/lib/foo.js
+  crc: a3f1c9e0
+---
+
+## Огляд
+
+…
+```
+
+## Оркестрацію веде JS, не модель; конвеєр — local-only
+
+Уся важка робота — черга, батчинг, виклики LLM і штамп CRC — живе в JS-команді
+`doc-files gen`. **Ти не диспатчиш субагентів і не тримаєш сотні файлів у контексті**
+— тому навіть масовий перший прогін усього репо не «заморює». Цей скіл **тонкий**: твоє завдання —
+запустити генерацію і прочитати підсумок.
+
+Конвеєр **суто локальний** (ADR `260610-2228`): будь-який файл генерується локальною
+моделлю (`omlx/…` напряму), хмарних ескалацій немає. Якщо det-оцінка нижча за поріг —
+дока все одно пишеться з **degraded-маркером** (`score`/`issues` у frontmatter, CRC свіжий),
+а перегенерація таких док — окремою командою пізніше.
+
+## Передумова
+
+- Поточна директорія — корінь проєкту (`requireRoot`), не worktree.
+- Доступний `npx @nitra/cursor`.
+
+## Workflow
+
+### Крок 1: Генерація застарілих/відсутніх док
+
+```bash
+npx @nitra/cursor doc-files gen
+```
+
+Команда сама: перевіряє omlx (preflight: «сервер лежить» / «модель не влазить у пам'ять
+зайнятої машини» / «потрібен API-ключ» → одна зрозуміла зупинка замість лавини «✗») →
+сканує проєкт → фільтрує застарілі (`stale`) → генерує локальною моделлю → пише доку зі
+**свіжим CRC** (і degraded-маркером, якщо не дотягнула) → друкує прогрес і підсумок.
+
+- Для дуже великого прогону можна порціями: `--from N --limit M`.
+- Перегенерувати **всі** доки (не лише застарілі): `--overwrite`.
+- Перегенерувати лише degraded (свіжі за CRC, score < порогу): `--retry-degraded`.
+
+### Крок 2: Підтвердження
+
+Дочекайся підсумку `✓ OK: <N>  ⚠ degraded: <D>  ✗ Err: <E>`. Якщо є помилки — перелічи
+проблемні файли. Exit-код `1` означає, що хоча б один файл не згенерувався (або не пройшов
+preflight). Degraded — не помилка: дока існує, борг видно у `check --degraded`.
+
+### Крок 3 (за потреби): перевірка перед завершенням
+
+```bash
+npx @nitra/cursor doc-files check --git
+```
+
+Перевіряє змінені у задачі джерела (`git diff --name-only HEAD`) проти CRC їхніх док.
+Цю ж перевірку виконує **Stop-hook** як твердий гейт: завершити задачу зі застарілими
+доками не можна (виняток — масовий прогін понад поріг `N_CURSOR_DOC_FILES_GATE_MAX`, дефолт 50).
+Degraded-доки гейт **не** блокує (CRC свіжий); їх список — `doc-files check --degraded`.
+
+## Правила стилю документа (за adr/ci4)
+
+- Мова — **УКРАЇНСЬКА** для всього тексту. Code identifiers, шляхи, імена API, команди — як у коді.
+- **Чистий Markdown.** Жодних HTML-обгорток. Єдиний виняток — машинний `docgen:`-frontmatter із CRC.
+- **Фокус на ПОВЕДІНЦІ, не реалізації.** ЩО і НАВІЩО, а не як саме зроблено.
+- Не перелічуй модулі стандартної бібліотеки і внутрішні назви допоміжних функцій.
+- Кожна секція самодостатня (без «як вище», «ця функція»).
+- Секції (лише доречні): `## Огляд`, `## Поведінка`, `## Публічний API`, `## Де використовується`,
+  `## Гарантії поведінки`; для `.vue` — `## Інтерфейс компонента`.
+- Не вигадуй деталей, яких немає в коді.
+
+## Нотатки
+
+- Не комітити автоматично — користувач вирішує, коли комітити згенеровану доку.
+- Scanner ігнорує `node_modules`, `dist`, `.git`, `__pycache__`, `coverage`, `.cursor`, `.claude`,
+  усі теки `docs/`, а також `*.test.*` / `*.spec.*` / `*.d.ts`. Кореневий repo `docs/` —
+  system-wide only: file-level docs туди не пишуться. Список glob-ів — `docgen-ignore.mjs`.
+- Агрегуюча документація (module-summary, доменні доки) — окремий скіл `doc-aggregate`, за запитом.
+- Для наявних док без CRC одноразово: `npx @nitra/cursor doc-files stamp` (штампує frontmatter без LLM).

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

@@ -0,0 +1,164 @@
+/**
+ * CRC32 джерела + YAML-frontmatter файлової документації.
+ *
+ * Кожна файлова дока несе у frontmatter контрольну суму байтів джерела на момент
+ * генерації. Це детермінований маркер застарілості: `crc32(поточне джерело)` звіряється
+ * з `crc` у доці — розбіжність (або відсутня дока) означає, що дока відстала від коду.
+ * CRC не залежить від git-стану (rebase, незакомічене, гілки), тож придатний і для
+ * per-edit hook (бачить лише змінений файл), і для повного сканування.
+ *
+ * Degraded-маркер (ADR 260610-2228): якщо локальний конвеєр не дотягнув до порогу
+ * якості, дока все одно пишеться, а frontmatter додатково несе `score` (det-оцінка)
+ * та `issues` (коди проблем). CRC при цьому свіжий — Stop-гейт не блокує задачі через
+ * слабкість моделі; борг видимий через `check --degraded` і адресно перегенеровується
+ * через `gen --retry-degraded`.
+ *
+ * Frontmatter — єдиний дозволений виняток із правила «чистий Markdown без HTML»:
+ * це машинні метадані, не контент. Формат:
+ *
+ *   ---
+ *   docgen:
+ *     source: src/lib/foo.js
+ *     crc: a3f1c9e0
+ *     score: 55
+ *     issues: short-behavior,internal-name:bar
+ *   ---
+ */
+import { existsSync, readFileSync } from 'node:fs'
+import { crc32 as zlibCrc32 } from 'node:zlib'
+import { env } from 'node:process'
+
+/** Поріг degraded: дока зі `score` нижче вважається неякісною. */
+export const QUALITY_THRESHOLD = Number(env.N_CURSOR_DOC_FILES_THRESHOLD ?? 70) || 70
+
+/**
+ * CRC32 вмісту у hex (8 символів, з провідними нулями). Делегує у нативний
+ * `node:zlib.crc32` — без ручної бітової арифметики.
+ * @param {string|Buffer} input текст або байти джерела
+ * @returns {string} CRC32 у hex
+ */
+export function crc32(input) {
+  const buf = typeof input === 'string' ? Buffer.from(input, 'utf8') : input
+  return zlibCrc32(buf).toString(16).padStart(8, '0')
+}
+
+/** Провідний YAML-frontmatter-блок `---\n…\n---`. */
+const FRONTMATTER_RE = /^---\n([\s\S]*?)\n---\n?/u
+const SOURCE_RE = /^[ \t]{0,8}source:[ \t]{0,8}(.+)$/mu
+const CRC_RE = /^[ \t]{0,8}crc:[ \t]{0,8}(.+)$/mu
+const SCORE_RE = /^[ \t]{0,8}score:[ \t]{0,8}(\d+)$/mu
+const ISSUES_RE = /^[ \t]{0,8}issues:[ \t]{0,8}(.+)$/mu
+const LEADING_NEWLINES_RE = /^\n+/u
+const ISSUE_CODE_TAIL_RE = /[,:]$/u
+
+/**
+ * Парсить frontmatter файлової доки. Без блоку — `data:null` і `body` дорівнює входу.
+ * Поля `score`/`issues` опційні (back-compat зі старими доками): без них —
+ * `score:null`, `issues:[]`.
+ * @param {string} md вміст md-файлу
+ * @returns {{ data: { source: string|null, crc: string|null, score: number|null, issues: string[] }|null, body: string }} метадані + тіло без frontmatter
+ */
+export function parseDocFrontmatter(md) {
+  const match = md.match(FRONTMATTER_RE)
+  if (!match) return { data: null, body: md }
+  const block = match[1]
+  const scoreRaw = block.match(SCORE_RE)?.[1]
+  const issuesRaw = block.match(ISSUES_RE)?.[1]
+  return {
+    data: {
+      source: block.match(SOURCE_RE)?.[1].trim() ?? null,
+      crc: block.match(CRC_RE)?.[1].trim() ?? null,
+      score: scoreRaw === undefined ? null : Number(scoreRaw),
+      issues: issuesRaw
+        ? issuesRaw
+            .split(',')
+            .map(s => s.trim())
+            .filter(Boolean)
+        : []
+    },
+    body: md.slice(match[0].length)
+  }
+}
+
+/** Максимум кодів issues у frontmatter — це маркер, а не повний лог. */
+const MAX_ISSUE_CODES = 8
+
+/**
+ * Нормалізує issues до YAML-безпечних кодів: бере фрагмент до першого пробілу
+ * (зрізає людиночитні хвости помилок), відкидає порожні, обмежує кількість.
+ * @param {string[]} issues сирі issue-рядки від скорера
+ * @returns {string[]} коди без пробілів
+ */
+function issueCodes(issues) {
+  return issues
+    .map(i => String(i).split(' ')[0].replace(ISSUE_CODE_TAIL_RE, ''))
+    .filter(Boolean)
+    .slice(0, MAX_ISSUE_CODES)
+}
+
+/**
+ * Будує frontmatter-блок із шляхом джерела, CRC і (опційно) якістю.
+ * @param {string} source відносний шлях джерела
+ * @param {string} crc CRC32 джерела у hex
+ * @param {{ score: number, issues?: string[] }|null} [quality] det-оцінка доки; null — без полів якості
+ * @returns {string} рядок `---\ndocgen:\n  source: …\n  crc: …[\n  score: …][\n  issues: …]\n---\n`
+ */
+export function buildDocFrontmatter(source, crc, quality = null) {
+  const lines = [`source: ${source}`, `crc: ${crc}`]
+  if (quality && typeof quality.score === 'number') {
+    lines.push(`score: ${quality.score}`)
+    const codes = issueCodes(quality.issues ?? [])
+    if (codes.length > 0) lines.push(`issues: ${codes.join(',')}`)
+  }
+  const indented = lines.map(l => '  ' + l).join('\n')
+  return `---\ndocgen:\n${indented}\n---\n`
+}
+
+/**
+ * (Пере)штампує frontmatter у md-доку: знімає наявний блок і додає свіжий.
+ * @param {string} md тіло доки (з frontmatter або без)
+ * @param {string} source відносний шлях джерела
+ * @param {string} crc CRC32 джерела у hex
+ * @param {{ score: number, issues?: string[] }|null} [quality] det-оцінка доки
+ * @returns {string} md зі свіжим frontmatter
+ */
+export function stampDoc(md, source, crc, quality = null) {
+  const { body } = parseDocFrontmatter(md)
+  return `${buildDocFrontmatter(source, crc, quality)}\n${body.replace(LEADING_NEWLINES_RE, '')}`
+}
+
+/**
+ * CRC, збережений у frontmatter доки; `null` — доки немає або CRC відсутній.
+ * @param {string} docAbsPath абсолютний шлях md-доки
+ * @returns {string|null} CRC32 з frontmatter або null
+ */
+export function readDocCrc(docAbsPath) {
+  if (!existsSync(docAbsPath)) return null
+  return parseDocFrontmatter(readFileSync(docAbsPath, 'utf8')).data?.crc ?? null
+}
+
+/**
+ * Якість, збережена у frontmatter доки.
+ * @param {string} docAbsPath абсолютний шлях md-доки
+ * @returns {{ score: number|null, issues: string[] }} `score:null` — доки немає або поле відсутнє
+ */
+export function readDocQuality(docAbsPath) {
+  if (!existsSync(docAbsPath)) return { score: null, issues: [] }
+  const data = parseDocFrontmatter(readFileSync(docAbsPath, 'utf8')).data
+  return { score: data?.score ?? null, issues: data?.issues ?? [] }
+}
+
+/**
+ * Стан застарілості доки відносно її джерела.
+ * `missing` — доки немає; `crc-mismatch` — CRC джерела ≠ CRC у доці; інакше свіжа.
+ * @param {string} sourceAbsPath абсолютний шлях джерела
+ * @param {string} docAbsPath абсолютний шлях md-доки
+ * @returns {{ stale: boolean, reason: 'missing'|'crc-mismatch'|null }} стан застарілості
+ */
+export function staleness(sourceAbsPath, docAbsPath) {
+  const docCrc = readDocCrc(docAbsPath)
+  if (docCrc === null) return { stale: true, reason: 'missing' }
+  const srcCrc = crc32(readFileSync(sourceAbsPath))
+  if (srcCrc !== docCrc) return { stale: true, reason: 'crc-mismatch' }
+  return { stale: false, reason: null }
+}

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

@@ -15,13 +15,23 @@
  */
 
 const URL_RE = /https?:\/\/[^\s'"`)<>]+/g
+// Після обрізання template-частини URL має лишитися host (R10).
+const STATIC_URL_RE = /^https?:\/\/[^/${]+/
 const EXPORT_CONST_RE = /export\s+const\s+([A-Z][A-Z0-9_]+)\s*=\s*(['"`])([^'"`]+)\2/g
 const ERROR_MARKER_RE = /\(([a-z][\w-]*\.mdc)\)/g
-const CONFIG_REF_RE = /\b(\.[a-z][\w.-]*\.json)\b/gi
+// Повне ім'я json-конфіга (з опційним провідним дотом). Lookbehind `(?<![\w.])`
+// не дає почати матч усередині складеного імені — інакше `settings.local.json`
+// дало б хибний анкор `.local.json`, а `capacitor.config.json` → `.config.json`,
+// і модель, маючи їх у «обов'язкових анкорах», писала б неіснуючий файл як факт.
+const CONFIG_REF_RE = /(?<![\w.])(\.?[a-z][\w.-]*\.json)\b/gi
 const FILE_HEADER_RE = /^\s*\/\*\*([\s\S]*?)\*\//
-const CODE_BLOCK_RE = /```[a-z]*\n([\s\S]*?)\n\s*\*?\s*```/g
+const CODE_BLOCK_RE = /```[a-z]{0,12}\n([\s\S]*?)\n[ \t]{0,8}\*?[ \t]{0,8}```/g
 
-/** Dedup масив, зберігаючи порядок появи. */
+/**
+ * Dedup масив, зберігаючи порядок появи.
+ * @param {Array<string>} arr вхідний масив
+ * @returns {Array<string>} масив без дублікатів у вихідному порядку
+ */
 function uniq(arr) {
   const seen = new Set()
   const out = []
@@ -36,17 +46,26 @@ function uniq(arr) {
 
 /**
  * Витягує анкори з вихідного коду файла.
- * @param {string} src
+ * @param {string} src вміст файлу
  * @returns {{
  *   urls: string[],
  *   magicStrings: Array<{name:string, value:string}>,
  *   errorMarkers: string[],
  *   configRefs: string[],
  *   examples: string[]
- * }}
+ * }} категоризовані анкори файлу
  */
 export function extractAnchors(src) {
-  const urls = uniq(Array.from(src.matchAll(URL_RE), m => m[0]))
+  // R10: template-literal URL (`https://h/${expr}/x`) — обрізаємо на `${`, лишаючи
+  // статичний префікс. Інакше анкор тягне у доку сміття типу `…/${encodeURIComponent(name`.
+  const urls = uniq(
+    Array.from(src.matchAll(URL_RE), m => m[0])
+      .map(u => {
+        const i = u.indexOf('${')
+        return i === -1 ? u : u.slice(0, i)
+      })
+      .filter(u => STATIC_URL_RE.test(u))
+  )
 
   const magicStrings = []
   const seenNames = new Set()
@@ -69,24 +88,40 @@ export function extractAnchors(src) {
   return { urls, magicStrings, errorMarkers, configRefs, examples }
 }
 
+/**
+ * Плоский список анкор-токенів, які мають дослівно зʼявитися в документі (R5):
+ * URLs, імена констант-рядків, маркери `(rule.mdc)`, конфіги. Приклади й
+ * code-блоки опускаються — їх багаторядковість не звіряється підрядком.
+ * @param {ReturnType<typeof extractAnchors>} a анкори файлу
+ * @returns {string[]} токени для перевірки покриття/валідності
+ */
+export function anchorTokens(a) {
+  return [...a.urls, ...a.magicStrings.map(s => s.name), ...a.errorMarkers.map(m => `(${m})`), ...a.configRefs]
+}
+
 /**
  * Форматує анкори у компактний текст для system-промпта.
  * Якщо анкорів немає взагалі — повертає порожній рядок (системний блок про
  * анкори не додається, щоб не вводити LLM в оману «обовʼязковими» полями).
- * @param {ReturnType<typeof extractAnchors>} a
- * @returns {string}
+ * @param {ReturnType<typeof extractAnchors>} a анкори файлу
+ * @returns {string} компактний текстовий блок або порожній рядок
  */
 export function anchorsToPrompt(a) {
   const blocks = []
   if (a.urls.length) blocks.push(`URLs (згадай у тексті): ${a.urls.join(', ')}`)
   if (a.magicStrings.length) {
-    blocks.push(
-      `Експортовані константи-рядки (наведи назву і призначення): ${a.magicStrings.map(s => `${s.name}=${JSON.stringify(s.value)}`).join('; ')}`
-    )
+    const consts = a.magicStrings.map(s => s.name + '=' + JSON.stringify(s.value)).join('; ')
+    blocks.push(`Експортовані константи-рядки (наведи назву і призначення): ${consts}`)
+  }
+  if (a.errorMarkers.length) {
+    const markers = a.errorMarkers.map(m => '(' + m + ')').join(', ')
+    blocks.push(`Маркери повідомлень (згадай у Поведінці): ${markers}`)
   }
-  if (a.errorMarkers.length) blocks.push(`Маркери повідомлень (згадай у Поведінці): ${a.errorMarkers.map(m => `(${m})`).join(', ')}`)
   if (a.configRefs.length) blocks.push(`Конфіги, на які спирається код: ${a.configRefs.join(', ')}`)
-  if (a.examples.length) blocks.push(`Приклади з документації автора (наведи дослівно у Поведінці):\n${a.examples.map(e => '```\n' + e + '\n```').join('\n')}`)
+  if (a.examples.length) {
+    const fenced = a.examples.map(e => '```\n' + e + '\n```').join('\n')
+    blocks.push(`Приклади з документації автора (наведи дослівно у Поведінці):\n${fenced}`)
+  }
   if (!blocks.length) return ''
   return `АНКОРИ ДО ОБОВ'ЯЗКОВОГО ВКЛЮЧЕННЯ:\n${blocks.join('\n')}`
 }

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

@@ -25,21 +25,29 @@ const BUILTIN_MODULES = new Set([
 const JSDOC_OPEN_RE = /^\s*\/\*\*?/
 const JSDOC_CLOSE_RE = /\*\/\s*$/
 const STAR_PREFIX_RE = /^\s*\*?\s?/
-const PARAM_LINE_RE = /^@param\s+(?:\{[^}]*\}\s+)?\[?([A-Za-z0-9_.]+)\]?\s*(.*)$/
-const RETURNS_LINE_RE = /^@returns?\s+(?:\{[^}]*\}\s+)?(.*)$/
+const PARAM_LINE_RE = /^@param[ \t]{1,8}(?:\{[^}]{0,200}\}[ \t]{1,8})?\[?([\w.]{1,80})\]?[ \t]{0,8}(.{0,400})$/
+const RETURNS_LINE_RE = /^@returns?[ \t]{1,8}(?:\{[^}]{0,200}\}[ \t]{1,8})?(.{0,400})$/
 const FILE_HEADER_RE = /^\s*\/\*\*([\s\S]*?)\*\//
 const PRECEDING_JSDOC_RE = /\/\*\*(?:(?!\*\/)[\s\S])*\*\/\s*$/
-const EXPORT_DECL_RE = /export\s+(?:async\s+)?(function|const|class)\s+([A-Za-z0-9_]+)/g
-const IMPORT_FROM_RE = /^import\s+[\s\S]*?from\s+['"]([^'"]+)['"]/gm
+const EXPORT_DECL_RE = /export\s+(?:async\s+)?(function|const|class)\s+(\w+)/g
+// Top-level function/class декларації (колонка 0) — для R6: службові функції,
+// які не експортуються, не мають протікати у Поведінку/API як «публічні».
+const TOP_FN_DECL_RE = /^(?:export\s+)?(?:default\s+)?(?:async\s+)?(?:function\*?|class)\s+(\w+)/gm
+const IMPORT_FROM_RE = /^import[ \t]{1,8}[\s\S]{0,300}?from\s{1,8}['"]([^'"]+)['"]/gm
 const NODE_PREFIX_RE = /^node:/
-const INTERNAL_IMPORT_RE = /import\s+(?:([A-Za-z0-9_$]+)\s*,?\s*)?(?:\{([^}]+)\})?\s+from\s+['"](\.[^'"]+)['"]/g
-const IMPORT_AS_RE = /\s+as\s+.*/
+const INTERNAL_IMPORT_RE = /import[ \t]{1,8}([^'"]{0,300}?)from[ \t]{1,8}['"]\.[^'"]{1,300}['"]/g
+const NAMED_BRACES_RE = /\{([^}]{1,400})\}/
+const IDENT_RE = /^[\w$]{1,80}$/
+const IMPORT_AS_RE = /[ \t]{1,8}as[ \t]{1,8}.{0,200}/
 const WRITE_FS_RE = /\b(writeFile|mkdir|rmdir|unlink|appendFile|createWriteStream|rm\()/
 const CATCH_RE = /catch\s*\(/
 const TRY_RE = /\btry\s*\{/
 const FALSY_RETURN_RE = /return\s+(false|null|''|"")/
 const NETWORK_RE = /\bfetch\(|https?\.|axios|got\(/
-const CACHE_RE = /new Map\(\)|Cache|cache/
+// Кеш — лише за ІМЕНОВАНИМ маркером (`cache`/`Cache`/`memoize`), не за будь-яким
+// `new Map()`: акумулятор (напр. `byPath = new Map()`) — не кеш, а хибна гарантія
+// «Кешує результати» гірша за пропуск (фабрикація > мовчання).
+const CACHE_RE = /cache|memoi[sz]e/i
 
 /**
  * Прибирає `/** *​/`-обрамлення й `*`-префікси, повертає чистий текст рядками.
@@ -152,12 +160,32 @@ function extractImports(src) {
 function extractInternalSymbols(src) {
   const out = new Set()
   for (const m of src.matchAll(INTERNAL_IMPORT_RE)) {
-    if (m[1]) out.add(m[1].trim())
-    if (m[2])
-      for (const n of m[2].split(',')) {
+    const clause = m[1]
+    const named = clause.match(NAMED_BRACES_RE)
+    if (named) {
+      for (const n of named[1].split(',')) {
         const name = n.replace(IMPORT_AS_RE, '').trim()
         if (name) out.add(name)
       }
+    }
+    const defName = clause.replace(NAMED_BRACES_RE, '').replaceAll(',', ' ').trim().split(' ')[0]
+    if (defName && IDENT_RE.test(defName)) out.add(defName)
+  }
+  return [...out]
+}
+
+/**
+ * Імена top-level функцій/класів, які НЕ експортуються (службові помічники).
+ * Модель не має подавати їх як «публічні функції» у Поведінці/API (R6).
+ * Const-стрілки свідомо не ловимо — менше false-positive на змістовних константах.
+ * @param {string} src вміст файлу
+ * @returns {Array<string>} список імен неекспортованих функцій/класів
+ */
+function extractLocalSymbols(src) {
+  const exported = new Set(Array.from(src.matchAll(EXPORT_DECL_RE), m => m[2]))
+  const out = new Set()
+  for (const m of src.matchAll(TOP_FN_DECL_RE)) {
+    if (!exported.has(m[1])) out.add(m[1])
   }
   return [...out]
 }
@@ -201,6 +229,7 @@ export function extractFacts(src, relPath) {
     exports: extractExports(src),
     imports: extractImports(src),
     internalSymbols: extractInternalSymbols(src),
+    localSymbols: extractLocalSymbols(src),
     markers: extractMarkers(src)
   }
 }