@7n/rules 1.49.25 → 1.50.0

package/rules/doc-files/docgen-prompts/main.mjs

@@ -15,7 +15,8 @@ export const STYLE = [
   'Заборонено: сигнатури, типи, параметри функцій; перелік stdlib-модулів; опис regex чи внутрішніх приватних імен.',
   // R9-профілактика: gemma-подібні малі моделі «озвучують завдання» перед відповіддю;
   // явна заборона з прикладами різко знижує частоту (дет-зрізання у stripSection — страховка).
-  'Виведи ЛИШЕ текст секції. ЗАБОРОНЕНО починати з мета-фраз на кшталт «Ось оновлена чорнетка…», «Оновлений текст секції:», «Як технічний письменник, я створю…» — одразу перший змістовний рядок.'
+  'Виведи ЛИШЕ текст секції. ЗАБОРОНЕНО починати з мета-фраз на кшталт «Ось оновлена чорнетка…», «Оновлений текст секції:», «Як технічний письменник, я створю…» — одразу перший змістовний рядок.',
+  'Не вигадуй маркери, конфігурації або code identifiers; порожній inline code `` заборонений.'
 ].join(' ')
 
 /**
@@ -46,8 +47,8 @@ function factsSummary(facts) {
   // безумовне «не пише» модель розганяє до хибного «гарантує безпечність» в Огляді.
   if (m.readOnly) lines.push('Власних операцій запису (ФС/БД) у файлі немає (імпортовані модулі не аналізувались)')
   if (m.network) lines.push('Звертається до мережі')
-  if (m.catchesErrors) lines.push('Перехоплює помилки (fail-safe), не кидає винятків назовні')
-  if (m.returnsFalsyOnFail) lines.push('За певних помилок повертає порожнє значення (напр. null) замість винятку')
+  if (m.catchesErrors) lines.push('Містить локальні fail-safe гілки; інші помилки можуть поширюватися назовні')
+  if (m.returnsFalsyOnFail) lines.push('Деякі локальні fail-safe гілки повертають порожнє значення (напр. null) замість винятку')
   lines.push(m.caches ? 'Кешування: так, у межах прогону' : 'Кешування: НЕМАЄ — не згадуй кеш у гарантіях')
   return lines.join('\n')
 }
@@ -85,9 +86,10 @@ function intentContext(intent) {
  * @param {string} src вміст файлу
  * @param {object|null} [anchors] анкори файлу для обовʼязкового включення
  * @param {string|null} [intent] захищена секція «Призначення» як read-only контекст
+ * @param {{ complementaryBehavior: boolean }} [opts] LLM доповнює лише прогалини між comments і кодом
  * @returns {Array<{key:string, messages:object[], numPredict:number}>} набір секційних промптів (лише behavior)
  */
-export function sectionMessages(facts, src, anchors = null, intent = null) {
+export function sectionMessages(facts, src, anchors = null, intent = null, { complementaryBehavior = false } = {}) {
   const factsTxt = factsSummary(facts)
   const anch = anchorsBlock(anchors)
   const intentCtx = intentContext(intent)
@@ -99,21 +101,26 @@ export function sectionMessages(facts, src, anchors = null, intent = null) {
   // його іншими словами. Натомість — крос-функціональний наратив: те, чого
   // немає в жодному окремому JSDoc за визначенням.
   const exportNames = (facts.exports ?? []).map(e => e.name)
-  const behaviorTask = multi
-    ? 'крос-функціональний потік: у якому порядку і як функції взаємодіють між собою, звідки приходять дані і куди йдуть результати, спільні правила чи стан. НЕ переказуй кожну функцію окремим пунктом — одно-рядкові описи вже є в секції «Публічний API»'
-    : 'нумерований алгоритм у бізнес-термінах'
+  const behaviorTask = complementaryBehavior
+    ? 'короткі поведінкові абзаци про відсутній користувацький контракт, без алгоритму'
+    : multi
+      ? 'крос-функціональний потік: у якому порядку і як функції взаємодіють між собою, звідки приходять дані і куди йдуть результати, спільні правила чи стан. НЕ переказуй кожну функцію окремим пунктом — одно-рядкові описи вже є в секції «Публічний API»'
+      : 'нумерований алгоритм у бізнес-термінах'
   const onlyExports = exportNames.length
     ? ` Описуй РІВНО ці публічні імена і жодних інших: ${exportNames.join(', ')}.`
     : ''
   const noInternal = facts.internalSymbols?.length
     ? ` НЕ згадуй за іменами службові функції: ${facts.internalSymbols.join(', ')}.`
     : ''
+  const complementaryInstruction = complementaryBehavior
+    ? ' «Огляд» і «Публічний API» уже дослівно зібрані з авторських коментарів. Додай ЛИШЕ відсутній для користувача контракт: умови, результат, error-flow, concurrency або інваріанти. Не перефразовуй авторський текст і НЕ переказуй реалізацію: заборонені обходи каталогів, цикли, читання файлів, AST-вузли, допоміжні виклики та нумерований алгоритм. Заборонені generic-фрази без факту з коду: «не вимагає налаштування», «виклик ініціює перевірку», «успішно повертається результат». Дай 1–4 короткі абзаци; якщо доповнювати нічого — поверни рівно NONE.'
+    : ''
   const behavior = {
     key: 'behavior',
     numPredict: 500,
     messages: msgs(
       `${STYLE}\n\nФАЙЛ ${facts.relPath}:\n\`\`\`\n${src}\n\`\`\`\n\nВІДОМІ ФАКТИ:\n${factsTxt}${anch}${intentCtx}`,
-      `Напиши вміст секції «Поведінка»: ${behaviorTask}.${onlyExports} Якщо у фактах є свідомі пропуски шляхів — згадай їх там, де доречно (не вигадуй інших «не перевіряє»). НЕ пиши аргументи функцій у дужках, без regex.${noInternal} Без заголовка, без додаткових ## чи # підзаголовків усередині секції.`
+      `Напиши вміст секції «Поведінка»: ${behaviorTask}.${onlyExports}${complementaryInstruction} Сценарії з test/spec-файлів рендерить JS окремою секцією — не згадуй і не відтворюй їх. Якщо у фактах є свідомі пропуски шляхів — згадай їх там, де доречно (не вигадуй інших «не перевіряє»). НЕ пиши аргументи функцій у дужках, без regex.${noInternal} Без заголовка, без додаткових ## чи # підзаголовків усередині секції.`
     )
   }
   return [behavior]
@@ -127,7 +134,7 @@ const STUB_DESC_RE = /^опис\.?$/i
 /**
  * Stage 2 (gap-детект, 0 токенів): чи є опис експорту прогалиною — відсутній
  * або JSDoc-заглушка без сенсу.
- * @param {{desc?:string}} exp запис експорту з факт-листа
+ * @param {{desc:string}} exp запис експорту з факт-листа
  * @returns {boolean} true — опис потрібно синтезувати LLM (Stage 3)
  */
 export function isApiGap(exp) {
@@ -255,8 +262,8 @@ export function guaranteesFromMarkers(facts) {
   // який file-local аналіз не може підтвердити. Обмежене твердження — може.
   if (m.readOnly)
     lines.push('- Власних операцій запису (ФС/БД) у файлі немає; виклики імпортованих модулів можуть писати.')
-  if (m.catchesErrors) lines.push('- Перехоплює помилки і не пропускає винятків назовні (fail-safe).')
-  if (m.returnsFalsyOnFail) lines.push('- За певних помилок повертає порожнє значення (напр. `null`) замість винятку.')
+  if (m.catchesErrors) lines.push('- Містить локальні fail-safe гілки; інші помилки можуть поширюватися назовні.')
+  if (m.returnsFalsyOnFail) lines.push('- Деякі локальні fail-safe гілки повертають порожнє значення (напр. `null`) замість винятку.')
   if (m.caches) lines.push('- Кешує результати в межах одного прогону.')
   if (m.skips?.length) {
     lines.push(`- Свідомо пропускає шляхи: ${m.skips.map(s => '`' + s + '`').join(', ')}.`)
@@ -275,7 +282,7 @@ export function oneShotMessages(facts, src) {
   const multi = (facts.exports?.length || 0) > 1
   return msgs(
     STYLE,
-    `Напиши документацію для файлу. Секції: ## Огляд (1-3 речення), ## Поведінка (нумерований/маркований алгоритм), ${multi ? '## Публічний API (назва + що робить), ' : ''}## Гарантії поведінки.\n\nФАЙЛ ${facts.relPath}:\n\`\`\`\n${src}\n\`\`\``
+    `Напиши документацію для файлу. Секції: ## Огляд (1-3 речення), ## Поведінка (нумерований/маркований алгоритм), ${multi ? '## Публічний API (назва + що робить), ' : ''}## Гарантії поведінки. Не додавай «Сценарії використання»: її детерміновано рендерить JS із повʼязаних test/spec-файлів.\n\nФАЙЛ ${facts.relPath}:\n\`\`\`\n${src}\n\`\`\``
   )
 }
 

package/rules/doc-files/docgen-scan/docs/main.md

@@ -3,50 +3,62 @@ type: JS Module
 title: main.mjs
 resource: npm/rules/doc-files/docgen-scan/main.mjs
 docgen:
-  crc: 8729f94f
-  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  crc: 9db666fe
+  model: openai-codex/gpt-5.5
+  tier: cloud-avg
   score: 100
-  issues: judge:inaccurate:0.99
+  issues: judge-refine:kept-original,judge:inaccurate:0.98
+  judgeModel: openai-codex/gpt-5.4-mini
 ---
 
 ## Огляд
 
-Модуль визначає, які файли є джерелами та обчислює відповідні шляхи для їхньої документації. Він сканує систему на наявність ізольованих або застарілих документів і надає засоби для ініціалізації сканування та перевірки якості існуючих документів.
+Файл сканує дерево проєкту й класифікує стан сусідньої поведінкової документації в `docs/` без власних операцій запису. Він визначає кодові кандидати через активні lang-плагіни, поважає `.gitignore`, пропускає тести й службові дерева, а для згенерованої документації оцінює docgen-CRC з урахуванням повʼязаних usage-сценаріїв.
+
+Публічні API-анкори: `isSourceFile`, `docPathForSource`, `isDocCandidate`, `scanForDocFiles`, `scanOrphanedDocs`, `describeFile`, `resolveRoot`.
+
+Стан документації розрізняє відсутню доку як `stale:missing`, свіжу як `stale:false`, змінену відносно CRC як `crc-mismatch`, а ручні або чужі документи як `foreign:true` без позначення застарілості. Docgen-документи з CRC лишаються `foreign:false` і перевіряються за CRC-семантикою. Orphan-сканування окремо знаходить документацію, для якої зник source, але не вважає orphan ручні документи, Directory Index і docs у службових деревах.
 
 ## Поведінка
 
-isSourceFile визначає, чи є ім'я файлу кодовим джерелом для генерації документації, виключаючи файли тестів і файли декларацій типів; перелік кодових розширень береться ВИКЛЮЧНО з декларацій активних lang-плагінів (`contributes.docFiles.extensions`: js/mjs/ts/vue — lang-js, `.rs`/`.py` — lang-rust/lang-python), у ядрі вбудованих розширень немає (фаза 5b) — без активного lang-плагіна скан не бачить жодного джерела.
-docPathForSource обчислює очікуваний шлях до markdown-документа для заданого кодового джерельного шляху, розміщуючи його у теці `docs` поруч із джерелом.
-isDocCandidate визначає, чи повинен файл підлягати документуванню, перевіряючи його тип, статус тесту, статус ігнорування та чи не є він частиною системних документації.
-describeFile описує кодовий файл, надаючи шлях джерела та шлях до відповідного документа, а також статус його застарілості за CRC. Якщо док-файл існує, але без `docgen:`-CRC у frontmatter (рукописна дока), файл позначається `foreign: true` і НЕ вважається застарілим — людський зміст рахується чинною документацією і мовчки не перезаписується (перезапис лише explicit `--overwrite` у batch-CLI).
-scanOrphanedDocs знаходить markdown-документи, які мають метадані про джерело, але відповідний код-файл більше не існує.
-scanForDocFiles обходить дерево від кореня і повертає список всіх кодових файлів, для яких може бути згенерована документація, з інформацією про їхній статус застарілості, виключаючи ті, що ігноруються через Git.
-resolveRoot визначає абсолютний кореневий каталог для сканування, беручи його з аргументів або використовуючи поточний робочий каталог.
-runDocFilesScanCli сканує вказане дерево та виводить у форматі JSON список усіх кодових файлів з їхнім статусом застарілості.
-runDocFilesCheckCli виконує перевірку на застарілість документації: може перевіряти один файл із stdin, групу змінених файлів через `git diff`, або звітувати про неякісні документи, блокуючи процес при знаходженні застарілого коду.
+`resolveRoot` визначає корінь обходу з CLI або поточної теки. Від цього кореня весь сканер читає конфігурацію активних lang-плагінів, застосовує правила пропуску й повертає відносні шляхи результатів.
 
-## Публічний API
+`scanForDocFiles` є основним потоком: обходить дерево від кореня, відсіює службові й ignored-дерева, root-level файли в system-wide docs layout, тести, `.d.ts` і некодові файли. Статус кандидата узгоджується через `isDocCandidate`, а кодове розширення — через `isSourceFile`. Розширення не вбудовані в ядро: JS/Vue, Python і Rust-файли стають джерелами лише тоді, коли їх декларують активні lang-плагіни; без такого плагіна файл не документується.
+
+Для кожного кандидата `docPathForSource` спрямовує документацію в сусідню теку `docs/` зі stem імені джерела. Далі `describeFile` порівнює стан документа з джерелом і повертає, чи потрібне оновлення: відсутня документація дає `missing`, зміна джерела або повʼязаного usage-сценарію дає `crc-mismatch`, збіг CRC означає актуальний документ.
 
-isSourceFile — визначає, чи є файл кодовим джерелом, що підлягає документуванню.
-docPathForSource — розраховує шлях до відповідного Markdown-документа, розміщуючи його в теці `docs/` поруч із кодом.
-isDocCandidate — вирішує, чи повинен файл підлягати документуванню: перевіряє розширення, виключення тестів, ігнорованих файлів та системних кореневих доків.
-describeFile — створює опис одного кодового файлу, включаючи його розташування, шлях доки, статус застарілості за CRC та ознаку `foreign` (рукописна дока без docgen-frontmatter — не ціль генерації).
-scanOrphanedDocs — шукає Markdown-документи, у яких вказано неіснуючий кодовий файл через `resource:` та `docgen.crc` у метаданих.
-scanForDocFiles — рекурсивно збирає всі кодові файли з дерева, повертаючи їх разом із статусом застарілості, фільтруючи за допомогою `git check-ignore`.
-resolveRoot — визначає корінь проекту для сканування, використовуючи аргумент `--root` або поточний робочий каталог.
-runDocFilesScanCli — сканує дерево та виводить у форматі JSON список усіх кодових файлів зі статусом застарілості.
-runDocFilesCheckCli — виконує перевірку на застарілість доків для хуків та CLI-інструментів.
+Рукописна документація має пріоритет над автоматичною генерацією. Якщо очікуваний doc-файл уже існує, але не має docgen-CRC у frontmatter, `describeFile` позначає його як foreign і не вважає stale. Це покриває як документи без frontmatter, так і документи з людським frontmatter без docgen-CRC; такі файли не мають мовчки перезаписуватись звичайним скануванням.
+
+`scanForDocFiles` поважає `.gitignore`: ignored source-файли не потрапляють у результат, а шляхи без ignore-маркера залишаються кандидатами. Якщо git-контекст недоступний або ignored-шляхів немає, сканування продовжується без помилки.
+
+`scanOrphanedDocs` працює окремим потоком очищення: шукає лише згенеровані doc-файли з resource і docgen-CRC та повідомляє ті, для яких source вже зник. Directory Index-документи з resource, що закінчується на `/`, ручні документи без CRC або без resource, а також документи всередині `node_modules` не вважаються orphan.
+
+## Публічний API
 
-Режими роботи:
---hook — перевіряє один файл, отриманий із вхідних даних, у контексті хука після використання інструменту.
---git — порівнює з поточним станом Git, блокуючи процес, якщо знайдено застарілі доки, перевищуючи встановлений поріг.
---degraded — виводить інформаційний звіт про доки, які не відповідають встановленому порогу.
-<paths...> — обробляє перелічені користувачем шляхи як джерела для документування.
+- isSourceFile — Чи є файл кодовим джерелом для документування. Розширення декларують ЛИШЕ
+активні lang-плагіни (`n-rules.contributes.docFiles.extensions` — js/mjs/ts/vue
+дає `@7n/rules-lang-js`, .rs/.py — lang-rust/lang-python); у ядрі вбудованих
+розширень немає (фаза 5b spec lang-plugins-extraction).
+- docPathForSource — Обчислює шлях md-документа для кодового файлу: тека `docs/` поряд із джерелом.
+Якщо `sourcePath` відносний, `docPath` теж відносний; якщо абсолютний — абсолютний.
+- isDocCandidate — Чи кодовий файл `relPath` (posix, від кореня) підлягає документуванню:
+правильне розширення, не тест, не в ignore-дереві, не кореневий system-wide docs.
+- describeFile — Описує один кодовий файл: шлях джерела, шлях доки, стан застарілості за CRC.
 
-Вихідний код (Exit 2) — вказує на знаходження застарілих доків (блокування хука); вихідний код (Exit 0) — вказує на відсутність проблем або успішне проходження понад встановлений поріг.
+`foreign: true` — docPath існує, але БЕЗ `docgen:`-CRC у frontmatter: рукописна
+(людська) дока. Така дока вважається чинною документацією файлу (`stale: false`) —
+генерація її мовчки не перезаписує (перезапис лише explicit `--overwrite`, який
+бере всі цілі без фільтра). Живий кейс: `npm/docs/index.md` — людський зміст модуля
+у проєкті-споживачі; сканер бачив його як `missing` і затирав чат-філером моделі.
+- scanOrphanedDocs — Знаходить "сирітські" доки: `docs/<stem>.md` із `resource:` + `docgen.crc` у frontmatter,
+у яких відповідний source-файл (resource:) вже не існує. Перевіряє лише файли,
+згенеровані `fix-doc-files` (наявність `docgen.crc` у frontmatter). Directory Index
+(resource із `/` на кінці) та ручні доки без `resource:` або без CRC — ігноруються.
+- scanForDocFiles — Рекурсивно обходить дерево від `root`, повертає кодові файли зі станом застарілості.
+Синхронний `readdirSync` — детермінований порядок без гонок; обсяг дерева це дозволяє.
+Поверх `DOCGEN_IGNORE_GLOBS` відсіює ще й те, що в `.gitignore` (через git check-ignore).
+- resolveRoot — Парсить `--root <dir>` з argv; default — cwd.
 
 ## Гарантії поведінки
 
-- Read-only: не виконує операцій запису (ФС/БД).
-- Перехоплює помилки і не пропускає винятків назовні (fail-safe).
-- За певних помилок повертає порожнє значення (напр. `null`) замість винятку.
+- Власних операцій запису (ФС/БД) у файлі немає; виклики імпортованих модулів можуть писати.

package/rules/doc-files/docgen-scan/main.mjs

@@ -6,6 +6,7 @@ import { execFileSync } from 'node:child_process'
 import { isDocgenIgnored } from '../docgen-ignore/main.mjs'
 import { parseDocFrontmatter, readDocCrc, staleness } from '../docgen-crc/main.mjs'
 import { pluginDocFilesExtensions } from './lang-extensions.mjs'
+import { buildTestEvidenceIndex } from '../docgen-test-context/main.mjs'
 
 /** `*.test.*`, `*.spec.*`, `*.stories.*` — тести й Storybook CSF-файли, документувати не треба. */
 const TEST_FILE_RE = /\.(?:test|spec|stories)\.[^.]+$/u
@@ -72,15 +73,16 @@ export function isDocCandidate(root, relPath) {
  * у проєкті-споживачі; сканер бачив його як `missing` і затирав чат-філером моделі.
  * @param {string} root абсолютний корінь
  * @param {string} sourcePath posix-шлях джерела від кореня
+ * @param {ReturnType<typeof buildTestEvidenceIndex>|null} [testIndex] source↔tests index
  * @returns {{sourcePath:string, docPath:string, stale:boolean, reason:'missing'|'crc-mismatch'|null, foreign:boolean}} опис файлу
  */
-export function describeFile(root, sourcePath) {
+export function describeFile(root, sourcePath, testIndex = null) {
   const docPath = docPathForSource(sourcePath)
   const docAbsPath = join(root, docPath)
   if (existsSync(docAbsPath) && readDocCrc(docAbsPath) === null) {
     return { sourcePath, docPath, stale: false, reason: null, foreign: true }
   }
-  const { stale, reason } = staleness(join(root, sourcePath), docAbsPath)
+  const { stale, reason } = staleness(join(root, sourcePath), docAbsPath, testIndex)
   return { sourcePath, docPath, stale, reason, foreign: false }
 }
 
@@ -190,6 +192,7 @@ function gitIgnoredPaths(root, relPaths) {
  */
 export function scanForDocFiles(root) {
   const results = []
+  const testIndex = buildTestEvidenceIndex(root)
 
   /** @param {string} dir поточний каталог обходу */
   function walk(dir) {
@@ -209,7 +212,7 @@ export function scanForDocFiles(root) {
         if (isSystemWideDocsRoot(root) && dirname(relPath) === '.') continue
         const sourcePath = relPath.split(sep).join('/')
         if (isDocgenIgnored(sourcePath)) continue
-        results.push(describeFile(root, sourcePath))
+        results.push(describeFile(root, sourcePath, testIndex))
       }
     }
   }

package/rules/doc-files/docgen-test-context/docs/index.md

@@ -0,0 +1,9 @@
+---
+type: Directory Index
+title: npm/rules/doc-files/docgen-test-context
+resource: npm/rules/doc-files/docgen-test-context/
+---
+
+| Файл                | Тип       |
+| ------------------- | --------- |
+| [main.mjs](main.md) | JS Module |

package/rules/doc-files/docgen-test-context/docs/main.md

@@ -0,0 +1,57 @@
+---
+type: JS Module
+title: main.mjs
+resource: npm/rules/doc-files/docgen-test-context/main.mjs
+docgen:
+  crc: 78bc0ee9
+  model: openai-codex/gpt-5.5
+  tier: cloud-avg
+  score: 100
+  issues: judge:error
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+## Огляд
+
+Файл визначає docgen test-файли, будує індекс підтверджень із тестів, знаходить тестові підтвердження для source-файлів, рендерить сценарії для документації та визначає source-файли, повʼязані з тестом, через `isDocgenTestFile`, `buildTestEvidenceIndex`, `testEvidenceForSource`, `renderTestScenarios`, `sourceFilesForTest`.
+
+Він існує, щоб документація могла посилатися на поведінку, підтверджену тестами, без зупинки процесу через нерозвʼязані або помилкові звʼязки. Локальні fail-safe гілки не дають окремим помилкам аналізу зірвати генерацію; інші помилки можуть поширюватися назовні.
+
+## Поведінка
+
+isDocgenTestFile визначає, чи файл може бути джерелом підтверджених usage-сценаріїв для документації. Це перший фільтр потоку: до подальшого аналізу потрапляють лише окремі test/spec-файли, тоді як вбудовані Rust unit-тести залишаються частиною самого source-файлу.
+
+buildTestEvidenceIndex обходить репозиторій, знаходить релевантні test/spec-файли та будує стабільний індекс звʼязків між source-файлами й тестами. Звʼязок вважається підтвердженим лише тоді, коли тест посилається на реальний файл через relative string literal і цей звʼязок схожий саме на тестування відповідного source, а не на допоміжний import.
+
+testEvidenceForSource читає індекс для конкретного source-файлу й перетворює знайдені тестові підтвердження на дані для документації та детермінований payload для перевірки актуальності. Тестовий код не передається в LLM prompt: у документацію потрапляють лише дослівні назви підтверджених сценаріїв, підготовлені для окремого JS-рендеру.
+
+renderTestScenarios приймає вже підготовлені тестові підтвердження та детерміновано формує компактний Markdown-фрагмент. Він не вигадує поведінку й не перефразовує тестові назви, а лише обмежує обсяг виводу, щоб документація не дублювала весь test-suite.
+
+sourceFilesForTest використовує той самий індекс у зворотному напрямку: для зміненого test/spec-файлу повертає source-файли, документацію яких потрібно вважати потенційно застарілою.
+
+Локальні fail-safe гілки під час аналізу не дають непідтвердженим або нерозвʼязаним звʼязкам потрапити у результат і не зупиняють генерацію документації. Власних записів у файлову систему чи базу даних цей модуль не виконує.
+
+## Публічний API
+
+- isDocgenTestFile — Чи шлях має форму окремого test/spec-файлу, який може описувати usage-сценарії.
+Rust unit-тести всередині source-файлу вже входять до самого джерела.
+- buildTestEvidenceIndex — Будує один source↔tests index на репозиторій. Зв'язок вважається доведеним
+лише через relative string literal, що резолвиться у реальний файл.
+- testEvidenceForSource — Формує дані для JS-рендеру сценаріїв і детермінований payload для CRC.
+Test-код не потрапляє до LLM prompt: опис тестового usage лишається дослівним.
+- renderTestScenarios — Детерміновано рендерить компактні підтверджені тестами сценарії у Markdown.
+Назви походять безпосередньо з `describe`/`test`/`it`, тому LLM не може їх
+перефразувати або додати неіснуючу поведінку; показуємо до пʼяти прикладів,
+а решту чесно рахуємо, щоб не дублювати весь test-suite у документації.
+- sourceFilesForTest — Source-файли, на які посилається конкретний змінений test/spec-файл.
+
+## Сценарії використання
+
+- `npm/rules/doc-files/docgen-test-context/tests/main.test.mjs` (isDocgenTestFile; buildTestEvidenceIndex) — розпізнає JS/TS test/spec і Python test naming; звичайний source-файл не є тестом; звʼязує source лише з тестом, що реально посилається на нього; інший сценарій; підтримує import без розширення і vi.mock relative reference; ще 4
+- `npm/rules/doc-files/tests/main.test.mjs` (lint — детект (read-only detector)) — ci (files=undefined): ловить відсутню доку у дереві; ci: свіжа дока → 0 violations; quick: змінене джерело без доки → violation; порожній набір → 0; quick: реверс-мапінг — змінена дока веде до перевірки джерела; quick: ігнорує test-файл без звʼязку із source; ще 5
+
+## Гарантії поведінки
+
+- Власних операцій запису (ФС/БД) у файлі немає; виклики імпортованих модулів можуть писати.
+- Містить локальні fail-safe гілки; інші помилки можуть поширюватися назовні.
+- Деякі локальні fail-safe гілки повертають порожнє значення (напр. `null`) замість винятку.

package/rules/doc-files/docgen-test-context/main.mjs

@@ -0,0 +1,212 @@
+/**
+ * @see ./docs/main.md
+ */
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs'
+import { basename, dirname, extname, join, relative, resolve, sep } from 'node:path'
+
+import { isDocgenIgnored } from '../docgen-ignore/main.mjs'
+
+const JS_TEST_RE = /\.(?:test|spec)\.(?:[cm]?[jt]sx?)$/u
+const RELATIVE_LITERAL_RE = /(['"])(\.{1,2}\/[^'"\n]+)\1/gu
+const SCENARIO_RE = /\b(describe|test|it)\s*\(\s*['"`]([^'"`\n]{1,200})['"`]/gu
+const QUERY_OR_HASH_RE = /[?#]/u
+const SOURCE_EXTENSIONS = Object.freeze(['.mjs', '.cjs', '.js', '.jsx', '.ts', '.tsx', '.vue', '.py', '.rs'])
+const TEST_SUFFIX_RE = /\.(?:test|spec)$/u
+
+/**
+ * Чи шлях має форму окремого test/spec-файлу, який може описувати usage-сценарії.
+ * Rust unit-тести всередині source-файлу вже входять до самого джерела.
+ * @param {string} fileName basename файлу
+ * @returns {boolean} true для JS/TS test/spec та Python test-файлів
+ */
+export function isDocgenTestFile(fileName) {
+  const pythonTest = fileName.endsWith('.py') && (fileName.startsWith('test_') || fileName.endsWith('_test.py'))
+  return JS_TEST_RE.test(fileName) || pythonTest
+}
+
+/**
+ * Рекурсивно знаходить test/spec-файли, поважаючи те саме ignore-дерево, що й doc-files.
+ * @param {string} root корінь репозиторію
+ * @returns {string[]} абсолютні шляхи у стабільному порядку
+ */
+function collectTestFiles(root) {
+  const out = []
+
+  /** @param {string} dir поточний каталог */
+  function walk(dir) {
+    let entries
+    try {
+      entries = readdirSync(dir, { withFileTypes: true })
+    } catch {
+      return
+    }
+    for (const entry of entries) {
+      const abs = join(dir, entry.name)
+      const rel = relative(root, abs).split(sep).join('/')
+      if (entry.isDirectory()) {
+        if (!isDocgenIgnored(rel, 'dir')) walk(abs)
+      } else if (entry.isFile() && isDocgenTestFile(entry.name) && !isDocgenIgnored(rel)) {
+        out.push(abs)
+      }
+    }
+  }
+
+  walk(root)
+  return out.toSorted()
+}
+
+/**
+ * Повертає наявний файл для relative module specifier-а з test-файлу.
+ * Підтримує explicit extension, import без розширення і directory index.
+ * @param {string} testAbs абсолютний шлях тесту
+ * @param {string} specifier relative specifier із рядкового літерала
+ * @returns {string|null} абсолютний шлях referenced-файлу
+ */
+function resolveRelativeReference(testAbs, specifier) {
+  const clean = specifier.split(QUERY_OR_HASH_RE, 1)[0]
+  const base = resolve(dirname(testAbs), clean)
+  const candidates = [base]
+  if (!extname(base)) {
+    for (const ext of SOURCE_EXTENSIONS) candidates.push(base + ext)
+    for (const ext of SOURCE_EXTENSIONS) candidates.push(join(base, `index${ext}`))
+  }
+  for (const candidate of candidates) {
+    try {
+      if (existsSync(candidate) && statSync(candidate).isFile()) return resolve(candidate)
+    } catch {
+      // Файл міг зникнути між existsSync/statSync — такий reference не беремо.
+    }
+  }
+  return null
+}
+
+/**
+ * Витягує файли, на які test/spec посилається relative string literal-ом.
+ * Це охоплює static/dynamic import, require, vi.mock та аналогічні API без
+ * прив'язки до конкретного test runner-а.
+ * @param {string} testAbs абсолютний шлях тесту
+ * @param {string} content вміст тесту
+ * @returns {string[]} абсолютні referenced-файли
+ */
+function referencedFiles(testAbs, content) {
+  const out = new Set()
+  for (const match of content.matchAll(RELATIVE_LITERAL_RE)) {
+    const referenced = resolveRelativeReference(testAbs, match[2])
+    if (referenced) out.add(referenced)
+  }
+  return [...out]
+}
+
+/**
+ * Відсіює helper imports: relative reference є необхідним, але не достатнім
+ * доказом, що тест описує поведінку саме цього source. Додатково вимагається
+ * naming (`foo.test` → `foo`) або module layout (`module/tests/*` → main/index).
+ * @param {string} testAbs абсолютний шлях тесту
+ * @param {string} sourceAbs абсолютний шлях referenced source
+ * @returns {boolean} true, якщо тест із високою ймовірністю є тестом source
+ */
+function isLikelyTestSubject(testAbs, sourceAbs) {
+  const testStem = basename(testAbs, extname(testAbs)).replace(TEST_SUFFIX_RE, '')
+  const sourceStem = basename(sourceAbs, extname(sourceAbs))
+  if (testStem === sourceStem) return true
+  if (sourceStem !== 'main' && sourceStem !== 'index') return false
+  const sourceDir = dirname(sourceAbs)
+  const testRel = relative(sourceDir, testAbs).split(sep).join('/')
+  return testStem === basename(sourceDir) || testRel.startsWith('tests/')
+}
+
+/**
+ * Будує один source↔tests index на репозиторій. Зв'язок вважається доведеним
+ * лише через relative string literal, що резолвиться у реальний файл.
+ * @param {string} root корінь репозиторію
+ * @returns {{ root: string, bySource: Map<string, Array<{absPath:string,relPath:string,content:string}>>, byTest: Map<string,string[]> }} source↔tests index
+ */
+export function buildTestEvidenceIndex(root) {
+  const normalizedRoot = resolve(root)
+  const bySource = new Map()
+  const byTest = new Map()
+  for (const testAbs of collectTestFiles(normalizedRoot)) {
+    let content
+    try {
+      content = readFileSync(testAbs, 'utf8')
+    } catch {
+      continue
+    }
+    const relPath = relative(normalizedRoot, testAbs).split(sep).join('/')
+    const sources = referencedFiles(testAbs, content).filter(sourceAbs => isLikelyTestSubject(testAbs, sourceAbs))
+    byTest.set(testAbs, sources)
+    for (const sourceAbs of sources) {
+      const tests = bySource.get(sourceAbs) ?? []
+      tests.push({ absPath: testAbs, relPath, content })
+      bySource.set(sourceAbs, tests)
+    }
+  }
+  return { root: normalizedRoot, bySource, byTest }
+}
+
+/**
+ * Витягує назви describe/test/it як короткі підтверджені usage-сценарії.
+ * `describe` дає контекст групи, а `test`/`it` — приклади поведінки; це дає
+ * змогу не перетворювати docs складного модуля на повний список unit-тестів.
+ * @param {string} content вміст тесту
+ * @returns {{ groups: string[], scenarios: string[] }} унікальні назви у порядку появи
+ */
+function scenarioNames(content) {
+  const groups = []
+  const scenarios = []
+  for (const match of content.matchAll(SCENARIO_RE)) {
+    const title = match[2].trim()
+    if (!title) continue
+    if (match[1] === 'describe') groups.push(title)
+    else scenarios.push(title)
+  }
+  return { groups: [...new Set(groups)], scenarios: [...new Set(scenarios)] }
+}
+
+/**
+ * Формує дані для JS-рендеру сценаріїв і детермінований payload для CRC.
+ * Test-код не потрапляє до LLM prompt: опис тестового usage лишається дослівним.
+ * @param {string} sourceAbs абсолютний шлях source-файлу
+ * @param {ReturnType<typeof buildTestEvidenceIndex>} index source↔tests index
+ * @returns {{ files: Array<{path:string,groups:string[],scenarios:string[]}>, crcPayload:string }} сценарії і повний CRC payload
+ */
+export function testEvidenceForSource(sourceAbs, index) {
+  const tests = index.bySource.get(resolve(sourceAbs)) ?? []
+  if (tests.length === 0) return { files: [], crcPayload: '' }
+
+  const files = tests.map(test => ({ path: test.relPath, ...scenarioNames(test.content) }))
+  const crcPayload = tests.map(test => `\0${test.relPath}\0${test.content}`).join('')
+  return { files, crcPayload }
+}
+
+/**
+ * Детерміновано рендерить компактні підтверджені тестами сценарії у Markdown.
+ * Назви походять безпосередньо з `describe`/`test`/`it`, тому LLM не може їх
+ * перефразувати або додати неіснуючу поведінку; показуємо до пʼяти прикладів,
+ * а решту чесно рахуємо, щоб не дублювати весь test-suite у документації.
+ * @param {Array<{path:string, groups?:string[], scenarios:string[]}>} files повʼязані test-файли зі сценаріями
+ * @returns {string} вміст секції «Сценарії використання» без заголовка
+ */
+export function renderTestScenarios(files) {
+  return files
+    .filter(test => test.scenarios.length > 0)
+    .map(test => {
+      const groups = (test.groups ?? []).slice(0, 2).join('; ')
+      const examples = test.scenarios.slice(0, 5).join('; ')
+      const rest = test.scenarios.length - 5
+      const scope = groups ? ` (${groups})` : ''
+      const more = rest > 0 ? `; ще ${rest}` : ''
+      return `- \`${test.path}\`${scope} — ${examples}${more}`
+    })
+    .join('\n')
+}
+
+/**
+ * Source-файли, на які посилається конкретний змінений test/spec-файл.
+ * @param {string} testAbs абсолютний шлях тесту
+ * @param {ReturnType<typeof buildTestEvidenceIndex>} index source↔tests index
+ * @returns {string[]} абсолютні source-шляхи
+ */
+export function sourceFilesForTest(testAbs, index) {
+  return index.byTest.get(resolve(testAbs)) ?? []
+}

package/rules/doc-files/main.mdc

@@ -1,5 +1,5 @@
 ---
-description: Файлова документація — обовʼязковий крок задачі (як lint); unified lint surface, concern doc-files/check — детект застарілості за CRC джерела + fix-by-default генерація local-only конвеєром (omlx)
+description: Файлова документація — обовʼязковий крок задачі (як lint); unified lint surface, concern doc-files/check — детект застарілості за CRC source + повʼязаних тестів і fix-by-default генерація local-only конвеєром (omlx)
 globs: "**/*.{js,mjs,ts,vue,py,rs},**/docs/**"
 alwaysApply: true
 version: '2.0'
@@ -7,7 +7,37 @@ version: '2.0'
 
 Кожен кодовий файл (`.js .mjs .ts .vue .py .rs`, крім тестів і `.d.ts`) має **актуальну**
 файлову доку поряд: `<dir>/docs/<stem>.md`. Це **обовʼязковий крок кожної задачі**, нарівні
-з lint. Актуальність детермінується за **CRC** джерела, записаним у frontmatter доки.
+з lint. Актуальність детермінується за **CRC evidence** — source + повʼязані test/spec-файли,
+записаним у frontmatter доки. Без повʼязаних тестів CRC лишається CRC самого source.
+
+## Тести як підтверджені usage-сценарії
+
+Test/spec-файли не отримують власної файлової доки, але доповнюють документацію source-файлу,
+якщо relative reference у тесті (`import`, `require`, dynamic import, `vi.mock` тощо)
+резолвиться саме в цей source і звʼязок підтверджує naming/layout (`foo.test` → `foo` або
+`module/tests/*` → module `main`/`index`). Це відсіює shared test helpers, які тест лише
+використовує. JS-оркестратор бере назви `describe`/`test`/`it` і детерміновано рендерить один
+компактний рядок на test-файл: до двох груп, пʼять дослівних прикладів і точний лічильник решти.
+Test-код і сценарії не передаються
+моделі, тож вона не може їх перефразувати або вигадати нові.
+
+Зміна повʼязаного тесту змінює evidence CRC і робить source-доку stale. У per-file режимі
+змінений тест reverse-map-иться до source-файлів, на які він посилається.
+
+## Авторські коментарі без LLM
+
+Якщо мовний екстрактор знайшов змістовний file header і змістовний опис кожного public API,
+doc-files збирає «Огляд» та «Публічний API» **дослівно**. Це працює для JSDoc (`/** */`),
+rustdoc (`//!`/`///`) і Python docstring-ів. У документ потрапляють також детерміновані
+«Сценарії використання» та «Гарантії поведінки».
+
+JS обирає один із трьох режимів:
+
+- `comment-only` — змістовний header вже пояснює потік; LLM і semantic judge не запускаються;
+- `comment+behavior` — короткий header/pointer без достатнього API-контракту або явний складний flow у коді: LLM пише лише
+  коротку «Поведінку», не може змінити авторські секції, а judge перевіряє тільки цей додаток;
+- `fallback` — header або хоча б один public API не має змістовного коментаря, тому лишається
+  звичний LLM-шлях.
 
 ## Одна команда — unified lint surface
 
@@ -25,13 +55,14 @@ unified lint surface (spec `docs/specs/2026-06-29-unified-lint-surface.md`) і
 
 ## Stale = `missing` ∪ `crc-mismatch`
 
-Дока застаріла, якщо її **немає** (`missing`) або `crc(джерело) ≠ crc` у frontmatter
+Дока застаріла, якщо її **немає** (`missing`) або `crc(source + related tests) ≠ crc` у frontmatter
 (`crc-mismatch`). Це і є `violations`, які повертає `lint(ctx)` концерну.
 
-Алгоритм детекту (кандидати, ignore-дерево, CRC, реверс-мапінг доки→джерело) — у
+Алгоритм детекту (кандидати, ignore-дерево, evidence CRC, реверс-мапінг доки/тесту→джерело) — у
 `docgen-scan/main.mjs` / `docgen-crc/main.mjs` / `docgen-ignore/main.mjs`, детектор — у
-`check/main.mjs` (`lint(ctx)`), fix — лише `check/fix-worker.mjs` (LLM-регенерація); тут —
-лише людинозрозумілий контракт, без дублювання логіки.
+`docgen-test-context/main.mjs` / `check/main.mjs` (`lint(ctx)`), fix — лише
+`check/fix-worker.mjs` (LLM-регенерація); тут — лише людинозрозумілий контракт, без
+дублювання логіки.
 
 T0-штампу CRC для `crc-mismatch` **немає навмисно**: свіжий CRC поверх старого тексту
 назавжди маскує дрейф (CRC-гейт вважає доку актуальною і вона більше не регенерується).