@nitra/cursor 5.2.0 → 5.2.1

package/rules/hasura/docs/fix.md

@@ -1,120 +1,27 @@
-# fix.mjs — entry-point правила `hasura`
+---
+docgen:
+  source: npm/rules/hasura/fix.mjs
+  crc: 12fc1644
+  score: 100
+---
 
-## Огляд
-
-Файл `npm/rules/hasura/fix.mjs` — тонкий entry-point для правила з ідентифікатором `hasura` у складі CLI-пакета `@nitra/cursor`. Виконує дві ролі одночасно:
-
-1. **Library mode** — експортує функцію `run(ctx)`, яка викликається з оркестратора CLI (наприклад, з `runRuleCli` або з агрегаторів типу `n-fix`), що дозволяє запускати правило в межах загального прогону всіх правил без породження окремого процесу.
-2. **Standalone mode** — якщо файл виконується безпосередньо (через `bun rules/<id>/fix.mjs` або `node rules/<id>/fix.mjs`), він виступає самостійним CLI-входом, повністю еквівалентним `npx @nitra/cursor fix hasura`: підвантажує config, застосовує whitelist, друкує summary та повертає процесний exit-code.
-
-Уся фактична логіка правила (послідовність кроків `applies → JS-concerns → policy → mdc-refs`) винесена в спільну реалізацію `runStandardRule` із бібліотечного шару `scripts/lib/`. Файл-обгортка несе лише прив'язку правила до власної директорії (через `import.meta.dirname`) та dispatch між двома режимами запуску.
-
-Відповідає конвенції двороль­ового `fix.mjs`, ухваленій для всіх «стандартних» правил у `npm/rules/*/`, тож має мінімальну поверхню коду й не містить специфіки `hasura`: тип правила, скоупи, перевірки та поліcі описуються деінде (`meta.json`, `hasura.mdc`, `js/`, `policy/`).
-
-## Експорти / API
-
-| Експорт | Тип                                      | Призначення                                                                                                                      |
-| ------- | ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
-| `run`   | `(ctx?: RuleContext) => Promise<number>` | Library-mode прогін правила в спільному CLI orchestration. Повертає `0` при відсутності порушень або `1` при наявності порушень. |
-
-Файл не має `default`-експорту й не експортує жодних інших символів.
-
-Поведінка при безпосередньому запуску файлу як скрипта — побічний ефект (top-level `await runRuleCli(...)` + `process.exit(...)`) і не є частиною програмного API.
-
-## Функції
-
-### `run(ctx)`
-
-Сигнатура: `export function run(ctx)`.
-
-- **Параметри:**
-  - `ctx` (`RuleContext`, опційний) — контекст прогону, що передається з оркестратора. Тип імпортовано (через JSDoc-tag `@param`) з `../../scripts/lib/run-standard-rule.mjs`. Очікувані поля контексту (за конвенцією `runStandardRule`) — спільні для всіх правил, серед них зокрема `walkCache` (кеш обходу файлової системи, щоб не повторювати walk між кількома правилами в одному прогоні). Якщо `ctx` не передано (`undefined`), `runStandardRule` сам ініціалізує мінімально необхідний контекст.
-- **Повертає:** `Promise<number>` — exit-code правила:
-  - `0` — застосовні файли пройшли всі етапи (`applies → JS-concerns → policy → mdc-refs`) без виявлених порушень.
-  - `1` — знайдено принаймні одне порушення (або зафіксована помилка валідації, що інтерпретується як failure).
-- **Side effects:**
-  - Делегує всю роботу `runStandardRule(import.meta.dirname, ctx)`, який, своєю чергою, читає файли правила (`meta.json`, `*.mdc`, `js/*.mjs`, `policy/*.rego`) із директорії, обходить цільові файли проєкту, друкує діагностичні повідомлення у stdout/stderr та повертає підсумкове число порушень. Сам `run` стану не модифікує.
-  - Прив'язує правило до своєї директорії саме через `import.meta.dirname`, тож при переміщенні файлу `fix.mjs` правило автоматично «переїде» разом із його артефактами (без хардкоду шляхів).
-
-### Безіменна процедура top-level (standalone-блок)
+# fix.mjs
 
-```js
-if (isRunAsCli(import.meta.url)) {
-  process.exit(await runRuleCli(import.meta.dirname))
-}
-```
-
-- **Тип:** виконується один раз під час завантаження модуля.
-- **Параметри:** немає (CLI-аргументи зчитуються всередині `runRuleCli` через `process.argv`).
-- **Повертає:** нічого (виконує `process.exit`).
-- **Side effects:**
-  - `isRunAsCli(import.meta.url)` визначає, чи модуль завантажено як прямий entry-point (а не як `import`).
-  - У випадку прямого запуску викликає `runRuleCli(import.meta.dirname)`, який повертає числовий exit-code, і негайно завершує процес із цим кодом через `process.exit`.
-  - Через `process.exit` подальші асинхронні задачі (мікротаски, відкриті ресурси) можуть бути обірвані — це свідомо: standalone entry-point повинен повертати чіткий код для CI/IDE-інтеграцій.
-- **Локальні правила лінту:**
-  - Поряд із викликом стоїть прагма `// eslint-disable-next-line n/no-process-exit, unicorn/no-process-exit -- standalone entry-point має повертати exit-code для CI/IDE`, оскільки за загальним правилом `process.exit` заборонений, але для CLI-входів дозволений.
-
-## Залежності
-
-### Внутрішні (відносні імпорти)
-
-- `../../scripts/lib/run-rule-cli.mjs`
-  - `isRunAsCli(metaUrl: string): boolean` — детектор «чи запущено модуль як скрипт». Зазвичай порівнює `import.meta.url` із URL виконуваного скрипта (`process.argv[1]`), щоб розрізнити `import` та прямий запуск.
-  - `runRuleCli(ruleDir: string): Promise<number>` — повноцінний CLI-runner: парсить аргументи, читає глобальний config (whitelist, severity, опції), запускає правило з директорії `ruleDir` і друкує summary. Повертає exit-code.
-- `../../scripts/lib/run-standard-rule.mjs`
-  - `runStandardRule(ruleDir: string, ctx?: RuleContext): Promise<number>` — стандартна послідовність кроків для «звичайного» правила: `applies → JS-concerns → policy → mdc-refs`. Це публічне ядро правил-обгорток на кшталт `fix.mjs`.
-  - `RuleContext` (тип) — імпортовано лише в JSDoc для типізації параметра `run`.
-
-### Зовнішні
-
-Прямих залежностей від npm-пакетів файл не має. Усі сторонні бібліотеки, які можуть знадобитися (наприклад, walker, парсер `.mdc`, OPA-обгортки тощо), використовуються транзитивно через `run-standard-rule.mjs` та `run-rule-cli.mjs`.
-
-### Залежність від файлів-побратимів у директорії правила
-
-Хоча `fix.mjs` сам нічого з них не читає, `runStandardRule(import.meta.dirname)` спирається на сусідні артефакти у тій же директорії правила `hasura/`:
-
-- `meta.json` — метадані правила (id, scope, опції тощо);
-- `hasura.mdc` — людинозрозумілий опис правила у форматі Cursor `.mdc`;
-- `js/` — JS-перевірки правила (`check-*.mjs`, fix-helpers);
-- `policy/` — Rego-полісі для OPA-кроку.
-
-Тож структурно файл `fix.mjs` має сенс лише як частина повної папки правила.
-
-## Потік виконання / Використання
-
-### Сценарій A — Library mode (з оркестратора)
+## Огляд
 
-1. Оркестратор (`n-cursor` CLI, агрегатор скілів, тести) робить `import { run } from '<path>/npm/rules/hasura/fix.mjs'`.
-2. Викликає `await run(ctx)`, передаючи контекст із попередньо побудованим `walkCache` та іншими опціями.
-3. `run` синхронно повертає результат виклику `runStandardRule(import.meta.dirname, ctx)`.
-4. `runStandardRule`:
-   - читає `meta.json` із директорії правила;
-   - проганяє послідовність `applies` (фільтр цільових файлів) → JS-concerns (динамічно підвантажені `js/check-*.mjs`) → policy (OPA з `policy/*.rego`) → mdc-refs (валідація `.mdc`-посилань);
-   - агрегує знахідки й повертає кількість порушень як exit-code (`0`/`1`).
-5. Оркестратор підсумовує exit-коди всіх правил.
+Цей файл ініціює застосування правил. Він запускає процес, що включає перевірку JS-занепокоєнь та політик. При самостійному запуску скрипт завантажує конфігурацію та вайтлістинг, а також надає звіт про виконання.
 
-### Сценарій B — Standalone CLI
+## Поведінка
 
-1. Користувач/CI виконує `bun npm/rules/hasura/fix.mjs [args...]`.
-2. На завантаженні модуля Node/Bun обчислює `isRunAsCli(import.meta.url)` — для прямого запуску результат `true`.
-3. Виконується `await runRuleCli(import.meta.dirname)`:
-   - парсинг CLI-аргументів (`--whitelist`, `--severity`, прапори `-q`/`-v` тощо — деталі в `run-rule-cli.mjs`);
-   - підвантаження конфіг-файлу пакета;
-   - застосування whitelist;
-   - виклик внутрішнього еквівалента `runStandardRule` для цієї ж директорії;
-   - друк summary-таблиці результатів.
-4. `process.exit(<exit-code>)` миттєво завершує процес зі значенням, яке повернув `runRuleCli`.
+1. Викликати функцію `run` для виконання правила. Це ініціює процес застосування правил, включаючи перевірку JS-занепокоєнь, політик та посилань MDC.
+2. Якщо скрипт виконується як окрема утиліта (standalone), викликати механізм оркестрації для виконання правила. Це забезпечує повну функціональність, включаючи завантаження конфігурації, вайтлістинг та підсумок.
 
-### Типові випадки використання
+## Публічний API
 
-- **CI:** `bun npm/rules/hasura/fix.mjs` як standalone-крок у пайплайні; ненульовий exit-code зриває build.
-- **Локально:** `npx @nitra/cursor fix hasura` запускає той самий entry-point через диспетчер CLI пакета (а не напряму).
-- **Інтеграція в IDE:** редактор може імпортувати `run` і викликати його в окремому процесі для отримання структурованого результату по правилу `hasura` (наприклад, через виклик `bun -e "import('...fix.mjs').then(m => m.run())"`).
-- **Агрегатори скілів** (наприклад, `n-fix`): паралельно або послідовно імпортують `run` із усіх правил `npm/rules/*/fix.mjs`, передають спільний `ctx` із `walkCache`, щоб уникнути повторного обходу файлової системи.
+run — виконує послідовність дій: застосовує правила, обробляє JavaScript-занепокоєння, перевіряє політику та посилання MDC.
 
-### Технічні зауваження щодо реалізації
+## Гарантії поведінки
 
-- `import.meta.dirname` (Node ≥ 20.11 / Bun) повертає абсолютний шлях до директорії модуля без потреби в `fileURLToPath(import.meta.url)`. Це поточний рекомендований спосіб локалізації власної директорії в ESM-модулях.
-- Прапор `await` у `process.exit(await runRuleCli(...))` працює завдяки top-level await у ESM — додаткової `main()`-обгортки не потрібно.
-- Свідомо обираний `process.exit` (а не «м'який» вихід через `process.exitCode = ...`) гарантує детермінований код повернення для CI/IDE навіть якщо хтось у фоновому таску щось «недописав».
-- Файл нейтральний щодо помилок: `runStandardRule` та `runRuleCli` самі вирішують, чи виносити exception у консоль і конвертувати її в exit-code; `fix.mjs` не обгортає виклики в `try/catch`.
+- Read-only: файл не виконує операцій запису у файлову систему.
+- Кешує результати в межах одного прогону.
+- Не звертається до мережі.

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

@@ -15,9 +15,15 @@
  */
 
 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]{0,12}\n([\s\S]*?)\n[ \t]{0,8}\*?[ \t]{0,8}```/g
 
@@ -50,7 +56,16 @@ function uniq(arr) {
  * }} категоризовані анкори файлу
  */
 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()
@@ -73,6 +88,17 @@ 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-промпта.
  * Якщо анкорів немає взагалі — повертає порожній рядок (системний блок про

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

@@ -30,6 +30,9 @@ const RETURNS_LINE_RE = /^@returns?[ \t]{1,8}(?:\{[^}]{0,200}\}[ \t]{1,8})?(.{0,
 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+(\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[ \t]{1,8}([^'"]{0,300}?)from[ \t]{1,8}['"]\.[^'"]{1,300}['"]/g
@@ -41,7 +44,10 @@ 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
 
 /**
  * Прибирає `/** *​/`-обрамлення й `*`-префікси, повертає чистий текст рядками.
@@ -168,6 +174,22 @@ function extractInternalSymbols(src) {
   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]
+}
+
 /**
  * Поведінкові маркери — евристики регулярками.
  * @param {string} src вміст файлу
@@ -207,6 +229,7 @@ export function extractFacts(src, relPath) {
     exports: extractExports(src),
     imports: extractImports(src),
     internalSymbols: extractInternalSymbols(src),
+    localSymbols: extractLocalSymbols(src),
     markers: extractMarkers(src)
   }
 }

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

@@ -7,11 +7,12 @@ import { DEFAULT_OMLX_MODEL } from '../../../lib/omlx.mjs'
 import { callLlm } from '../../../lib/llm.mjs'
 import { isRunAsCli } from '../../../scripts/cli-entry.mjs'
 import { extractFacts } from './docgen-extract.mjs'
-import { extractAnchors } from './docgen-extract-anchors.mjs'
+import { extractAnchors, anchorTokens } from './docgen-extract-anchors.mjs'
 import { QUALITY_THRESHOLD } from './docgen-crc.mjs'
 import {
   oneShotMessages,
   sectionMessages,
+  overviewMessages,
   criticMessages,
   refineMessages,
   guaranteesFromMarkers
@@ -25,6 +26,15 @@ const SECTION_KEY_CLEAN_RE = /[^а-яіїєґa-z0-9]/gi
 const CACHE_MENTION_RE = /кеш/i
 const CACHE_NEGATION_RE = /(?:не|без)\s+(?:\S+\s+)?кеш|немає\s+кеш/i
 const CRITIC_NONE_RE = /^\s*NONE\s*$/i
+// R4: абстрактні «нічого-не-кажучі» формули, які обходять exact-blocklist і дають score=100
+const GENERIC_RE =
+  /відповідност\S*\s+(?:даних\s+)?(?:визначеному\s+)?контракту|валідаці\S*\s+даних|перевірк\S*\s+(?:відповідності\s+)?даних|обробк\S*\s+даних|застосову\S*\s+логіку|інспекту\S*\s+та\s+збира\S*\s+дан/i
+// R7: часті русизми/суржик (курований безпечний список — без false-positive на нормальній мові).
+// Без \b: кирилиця не є ASCII-`\w`, тож межі слова в JS-regex не спрацьовують — терміни специфічні.
+const SURZHIK_RE =
+  /пропуская|являється|в залежності|по замовчуванню|на протязі|відповідаюч|слідуюч|наступним разом|приймати участь|у відповідності/i
+const ANCHOR_MISS_PENALTY = 5
+const ANCHOR_MISS_CAP = 20
 
 /**
  * Прибирає код-фенс-обгортку (потрійні бектіки) й випадковий провідний
@@ -86,18 +96,26 @@ function hasName(text, sym) {
  * Stage 2.5 — детермінований скоринг (0 токенів): перевіряє вихід проти фактів.
  * @param {string} md зібраний документ
  * @param {object} facts факт-лист про файл
+ * @param {{ anchors?: object|null, src?: string }} [ctx] анкори й джерело для R5
  * @returns {{ score: number, issues: string[] }} оцінка 0–100 і коди проблем
  */
-function scoreDoc(md, facts) {
+export function scoreDoc(md, facts, { anchors = null, src = '' } = {}) {
   const s = parseSections(md)
   let score = 100
   const issues = []
+  const overview = s['огляд'] ?? ''
 
   if (!s['огляд']) {
     score -= 25
     issues.push('no-overview')
   }
 
+  // R4: generic-Огляд (парафрази, які обходять exact-blocklist) — як майже-відсутній.
+  if (GENERIC_RE.test(overview)) {
+    score -= 35
+    issues.push('generic-overview')
+  }
+
   const behavior = s['поведінка'] ?? ''
   if (behavior.length < 60) {
     score -= 20
@@ -113,14 +131,35 @@ function scoreDoc(md, facts) {
     issues.push('cache-hallucination')
   }
 
-  for (const sym of facts.internalSymbols ?? []) {
-    const inDoc = hasName(guarantees, sym) || hasName(s['огляд'] ?? '', sym) || hasName(s['поведінка'] ?? '', sym)
+  // R6: службові (неекспортовані) функції не мають фігурувати як публічні
+  const api = s['публічнийapi'] ?? ''
+  for (const sym of [...(facts.internalSymbols ?? []), ...(facts.localSymbols ?? [])]) {
+    const inDoc = hasName(guarantees, sym) || hasName(overview, sym) || hasName(behavior, sym) || hasName(api, sym)
     if (inDoc) {
       score -= 10
       issues.push(`internal-name:${sym}`)
     }
   }
 
+  // R5: кожен валідний анкор (дослівний підрядок src) має зʼявитися в документі
+  if (anchors && src) {
+    let missPenalty = 0
+    for (const tok of anchorTokens(anchors)) {
+      if (!src.includes(tok)) continue // валідність: фейковий анкор не вимагаємо
+      if (!md.includes(tok) && missPenalty < ANCHOR_MISS_CAP) {
+        missPenalty += ANCHOR_MISS_PENALTY
+        issues.push(`anchor-miss:${tok}`)
+      }
+    }
+    score -= missPenalty
+  }
+
+  // R7: суржик/русизми
+  if (SURZHIK_RE.test(md)) {
+    score -= 10
+    issues.push('surzhik')
+  }
+
   return { score: Math.max(0, score), issues }
 }
 
@@ -205,15 +244,21 @@ function orchestratedDoc(facts, src, model, timeoutMs, { anchors = null, tempera
   const anc = anchors ?? extractAnchors(src)
   // E3: «Гарантії» — детермінований шаблон з markers (0 LLM-запитів, 0 generic-фраз)
   sections.guarantees = guaranteesFromMarkers(facts)
+  // Спершу Поведінка (+API) — секції з фактажем
   for (const s of sectionMessages(facts, src, anc)) {
-    if (s.key === 'guarantees') continue // вже згенеровано детерміновано
     let draft = stripSignatures(stripSection(callLlm(s.messages, model, { timeoutMs, temperature })))
-    // E2 + E3: critique→refine лише для секцій, де мала модель зриває на generic
-    if (s.key === 'overview' || (s.key === 'api' && apiNeedsRefine(facts))) {
+    // E2: critique→refine для API, коли всі описи порожні (модель зриває на generic)
+    if (s.key === 'api' && apiNeedsRefine(facts)) {
       draft = critiqueRefineSection(s.key, draft, facts, anc, model, timeoutMs)
     }
     sections[s.key] = draft
   }
+  // R3: «Огляд» — ОСТАННІМ, узагальненням уже написаної Поведінки (не голого факт-листа)
+  let overview = stripSignatures(
+    stripSection(callLlm(overviewMessages(facts, sections.behavior ?? '', anc), model, { timeoutMs, temperature }))
+  )
+  overview = critiqueRefineSection('overview', overview, facts, anc, model, timeoutMs)
+  sections.overview = overview
   return { md: assemble(basename(facts.relPath), sections) }
 }
 
@@ -253,13 +298,13 @@ export function generateDoc(file, { model = DEFAULT_LOCAL_MODEL, threshold = QUA
   }
 
   // Stage 2.5: детермінований скоринг (0 токенів)
-  let { score, issues } = scoreDoc(r.md, facts)
+  let { score, issues } = scoreDoc(r.md, facts, { anchors, src })
 
   // E4: best-of-2 — один retry з вищою температурою, det-вибір кращого
   if (score < threshold && env.N_CURSOR_DOCGEN_BEST_OF !== '0') {
     try {
       const r2 = orchestratedDoc(facts, src, model, LOCAL_TIMEOUT_MS, { anchors, temperature: 0.5 })
-      const s2 = scoreDoc(r2.md, facts)
+      const s2 = scoreDoc(r2.md, facts, { anchors, src })
       if (s2.score > score) {
         r = r2
         score = s2.score

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

@@ -52,31 +52,26 @@ const msgs = (system, user) => [
 
 /**
  * Секційні набори messages з МІНІМАЛЬНИМ контекстом під кожну секцію.
- * Код потрапляє лише в `behavior`; решта секцій — на факт-листі.
+ * Код потрапляє лише в `behavior`; «Огляд» генерується окремо ОСТАННІМ
+ * (`overviewMessages`) з уже написаної Поведінки — тут його немає.
  * @param {object} facts факт-лист про файл
  * @param {string} src вміст файлу
  * @param {object|null} [anchors] анкори файлу для обовʼязкового включення
- * @returns {Array<{key:string, messages:object[], numPredict:number}>} набір секційних промптів
+ * @returns {Array<{key:string, messages:object[], numPredict:number}>} набір секційних промптів (behavior[, api])
  */
 export function sectionMessages(facts, src, anchors = null) {
   const factsTxt = factsSummary(facts)
   const anch = anchorsBlock(anchors)
   const multi = (facts.exports?.length || 0) > 1
 
-  // Огляд — лише факти (без коду)
-  const overview = {
-    key: 'overview',
-    numPredict: 220,
-    messages: msgs(
-      `${STYLE}\n\nВІДОМІ ФАКТИ:\n${factsTxt}${anch}`,
-      'Напиши вміст секції «Огляд»: 1-3 речення — що файл робить і навіщо існує (роль у системі). Без заголовка, без переліку функцій. Заборонені generic-фрази типу «забезпечує перевірку», «виконує валідацію» — пиши КОНКРЕТНО що саме і за яким контрактом.'
-    )
-  }
-
-  // Поведінка — ЄДИНА секція, якій потрібен код
+  // R6: Поведінка описує РІВНО експортовані імена, не службові помічники
+  const exportNames = (facts.exports ?? []).map(e => e.name)
   const behaviorTask = multi
     ? 'для кожної публічної функції — один короткий пункт «що вона робить»'
     : 'нумерований алгоритм у бізнес-термінах'
+  const onlyExports = exportNames.length
+    ? ` Описуй РІВНО ці публічні імена і жодних інших: ${exportNames.join(', ')}.`
+    : ''
   const noInternal = facts.internalSymbols?.length
     ? ` НЕ згадуй за іменами службові функції: ${facts.internalSymbols.join(', ')}.`
     : ''
@@ -85,12 +80,12 @@ export function sectionMessages(facts, src, anchors = null) {
     numPredict: 500,
     messages: msgs(
       `${STYLE}\n\nФАЙЛ ${facts.relPath}:\n\`\`\`\n${src}\n\`\`\`\n\nВІДОМІ ФАКТИ:\n${factsTxt}${anch}`,
-      `Напиши вміст секції «Поведінка»: ${behaviorTask}. Якщо у фактах є свідомі пропуски шляхів — згадай їх там, де доречно (не вигадуй інших «не перевіряє»). НЕ пиши аргументи функцій у дужках, без regex.${noInternal} Без заголовка, без додаткових ## чи # підзаголовків усередині секції.`
+      `Напиши вміст секції «Поведінка»: ${behaviorTask}.${onlyExports} Якщо у фактах є свідомі пропуски шляхів — згадай їх там, де доречно (не вигадуй інших «не перевіряє»). НЕ пиши аргументи функцій у дужках, без regex.${noInternal} Без заголовка, без додаткових ## чи # підзаголовків усередині секції.`
     )
   }
 
   // API — лише список експортів (без коду)
-  if (!multi && !facts.exports?.some(e => e.desc)) return [overview, behavior]
+  if (!multi && !facts.exports?.some(e => e.desc)) return [behavior]
   const list = facts.exports.map(e => `- ${e.name}: ${e.desc || '(сформулюй стисло з наміру файлу)'}`).join('\n')
   const api = {
     key: 'api',
@@ -100,7 +95,24 @@ export function sectionMessages(facts, src, anchors = null) {
       `Перепиши цей список як стислі маркери «назва — що робить», СВОЇМИ словами (не копіюй дослівно), без типів і сигнатур. Використовуй РІВНО ці назви, не додавай і не прибирай:\n${list}\nБез заголовка. Без generic-фраз «застосовує логіку», «перевіряє коректність» — пиши конкретно ЩО саме застосовує/перевіряє.`
     )
   }
-  return [overview, behavior, api]
+  return [behavior, api]
+}
+
+/**
+ * R3 — «Огляд» ОСТАННІМ: узагальнення вже написаної Поведінки, а не здогад із
+ * голого факт-листа. Лікує generic/хибний Огляд на складних файлах.
+ * @param {object} facts факт-лист про файл
+ * @param {string} behaviorText готовий текст секції «Поведінка»
+ * @param {object|null} [anchors] анкори файлу
+ * @returns {Array<{role:string,content:string}>} messages-масив для Огляду
+ */
+export function overviewMessages(facts, behaviorText, anchors = null) {
+  const factsTxt = factsSummary(facts)
+  const anch = anchorsBlock(anchors)
+  return msgs(
+    `${STYLE}\n\nВІДОМІ ФАКТИ:\n${factsTxt}${anch}`,
+    `На основі вже написаної секції «Поведінка» (нижче) напиши «Огляд»: 1-3 речення — що файл робить і навіщо існує (роль у системі). Узагальнюй САМЕ описану поведінку, не додавай нових фактів. Без заголовка, без переліку функцій. Заборонені абстрактні формули без конкретики («перевірка/валідація/обробка даних», «відповідність контракту», «застосовує логіку») — пиши, ЩО саме і за яким контрактом.\n\nПОВЕДІНКА:\n${behaviorText}`
+  )
 }
 
 /**

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

@@ -0,0 +1,139 @@
+/** @see ./docs/units-js.md */
+
+import { parseProgramOrNull, walkAstWithAncestors } from '../../../scripts/utils/ast-scan-utils.mjs'
+
+// JSDoc-блок, що стоїть впритул перед позицією (лише пробіли між ними).
+const JSDOC_BEFORE_RE = /\/\*\*(?:(?!\*\/)[\s\S])*\*\/\s*$/
+const JSDOC_OPEN_RE = /^\s*\/\*\*?/
+const JSDOC_CLOSE_RE = /\*\/\s*$/
+const STAR_PREFIX_RE = /^\s*\*?\s?/
+
+/**
+ * Очищає JSDoc від обрамлення `/** *​/` і `*`-префіксів.
+ * @param {string} raw сирий блок або порожній рядок
+ * @returns {string} текст опису без тегів-обрамлення
+ */
+function cleanDoc(raw) {
+  if (!raw) return ''
+  return raw
+    .replace(JSDOC_OPEN_RE, '')
+    .replace(JSDOC_CLOSE_RE, '')
+    .split('\n')
+    .map(l => l.replace(STAR_PREFIX_RE, '').trimEnd())
+    .join('\n')
+    .trim()
+}
+
+/**
+ * JSDoc, що передує позиції `start` у джерелі (або порожній рядок).
+ * @param {string} src вміст файлу
+ * @param {number} start зміщення початку декларації
+ * @returns {string} очищений опис
+ */
+function precedingDoc(src, start) {
+  const m = src.slice(0, start).match(JSDOC_BEFORE_RE)
+  return cleanDoc(m ? m[0] : '')
+}
+
+/**
+ * Імʼя функції, що викликається (проста Identifier або `obj.method`).
+ * @param {Record<string, unknown>} node CallExpression
+ * @returns {string|null} імʼя callee або null
+ */
+function calleeName(node) {
+  const c = node.callee
+  if (!c || typeof c !== 'object') return null
+  if (c.type === 'Identifier') return c.name
+  if (c.type === 'MemberExpression' && !c.computed && c.property?.type === 'Identifier') return c.property.name
+  return null
+}
+
+/**
+ * Множина імен, що викликаються у тілі вузла (сирі callee — фільтрація на ребра
+ * call-graph робиться у `extractUnitsJs` після збору всіх імен юнітів).
+ * @param {unknown} node AST-вузол юніта
+ * @returns {Set<string>} імена викликів
+ */
+function collectCalls(node) {
+  const names = new Set()
+  walkAstWithAncestors(node, [], n => {
+    if (n.type === 'CallExpression') {
+      const name = calleeName(n)
+      if (name) names.add(name)
+    }
+  })
+  return names
+}
+
+/**
+ * Будує юніт із декларації, додає у `units`. Розпізнає function/class та
+ * const-функції (`const x = () => {}` / `function expression`).
+ * @param {Record<string, unknown>} decl декларація (function/class/variable)
+ * @param {boolean} exported чи експортується
+ * @param {number} docStart зміщення для пошуку JSDoc (зовнішній export-вузол)
+ * @param {string} src вміст файлу
+ * @param {Array<object>} units акумулятор
+ * @returns {void}
+ */
+function pushUnits(decl, exported, docStart, src, units) {
+  if (!decl || typeof decl !== 'object') return
+  const doc = precedingDoc(src, docStart)
+  if (decl.type === 'FunctionDeclaration' || decl.type === 'ClassDeclaration') {
+    const name = decl.id?.name
+    if (!name) return
+    units.push({
+      name,
+      kind: decl.type === 'ClassDeclaration' ? 'class' : 'function',
+      exported,
+      span: { start: decl.start, end: decl.end },
+      body: src.slice(decl.start, decl.end),
+      calls: collectCalls(decl),
+      doc
+    })
+    return
+  }
+  if (decl.type === 'VariableDeclaration') {
+    for (const d of decl.declarations ?? []) {
+      const init = d.init
+      const isFn = init && (init.type === 'ArrowFunctionExpression' || init.type === 'FunctionExpression')
+      if (!isFn || d.id?.type !== 'Identifier') continue
+      units.push({
+        name: d.id.name,
+        kind: 'const',
+        exported,
+        span: { start: init.start, end: init.end },
+        body: src.slice(init.start, init.end),
+        calls: collectCalls(init),
+        doc
+      })
+    }
+  }
+}
+
+/**
+ * Юніт-шар для js/mjs/ts: top-level функції/класи/const-функції з тілом, JSDoc,
+ * прапором експорту і ребрами call-graph (виклики ІНШИХ юнітів у тілі).
+ * @param {string} src вміст файлу
+ * @param {string} [relPath] шлях (для вибору мови oxc)
+ * @returns {Array<{name:string, kind:string, exported:boolean, span:{start:number,end:number}, body:string, calls:string[], doc:string}>|null} юніти або null, якщо файл не парситься
+ */
+export function extractUnitsJs(src, relPath = 'scan.ts') {
+  const program = parseProgramOrNull(src, relPath)
+  if (!program || !Array.isArray(program.body)) return null
+
+  const units = []
+  for (const node of program.body) {
+    if (node.type === 'ExportNamedDeclaration' && node.declaration) {
+      pushUnits(node.declaration, true, node.start, src, units)
+    } else if (node.type === 'ExportDefaultDeclaration' && node.declaration) {
+      pushUnits(node.declaration, true, node.start, src, units)
+    } else {
+      pushUnits(node, false, node.start, src, units)
+    }
+  }
+
+  // Ребра call-graph: лишаємо тільки виклики інших внутрішніх юнітів
+  const names = new Set(units.map(u => u.name))
+  for (const u of units) u.calls = [...u.calls].filter(n => names.has(n) && n !== u.name)
+  return units
+}

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

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