@7n/rules 1.49.26 → 1.50.0

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

@@ -8,6 +8,7 @@ import { startChain } from '@7n/llm-lib/chain'
 import { isRunAsCli } from '../../../scripts/cli-entry.mjs'
 import { docPathForSource } from '../docgen-scan/main.mjs'
 import { loadDocFilesExtractors } from '../docgen-scan/lang-extensions.mjs'
+import { buildTestEvidenceIndex, renderTestScenarios, testEvidenceForSource } from '../docgen-test-context/main.mjs'
 import { extractAnchors, anchorTokens } from '../docgen-extract-anchors/main.mjs'
 import { QUALITY_THRESHOLD } from '../docgen-crc/main.mjs'
 import { JUDGE_ENABLED, JUDGE_MODEL, detectRefusalFiller, judgeDoc, judgeFailsDoc } from '../docgen-judge/main.mjs'
@@ -93,6 +94,13 @@ async function callLlm(messages, model, opts = {}) {
 
 const FENCE_OPEN_RE = /^```[a-z]*\n?/
 const FENCE_CLOSE_RE = /\n?```\s*$/
+const EMPTY_INLINE_CODE_RE = /``/g
+// Порожній code span — артефакт LLM, а не валідний факт про файл. Зрізаємо всю
+// фразу: інакше після видалення лише `` лишається вигадане твердження довкола.
+const EMPTY_INLINE_CODE_SENTENCE_RE = /[^.!?\n]*``[^.!?\n]*[.!?]/g
+// Внутрішній приклад із коментарів на кшталт `(foo.mdc)` не є поведінкою
+// модуля. Модель інколи переносить його у prose, тому таку фразу відкидаємо.
+const PAREN_MDC_SENTENCE_RE = /[^.!?\n]*\([^()\n]+\.mdc\)[^.!?\n]*[.!?]/g
 const LEADING_HEADING_RE = /^#{1,6}[ \t]{1,8}[^\n]{0,400}\n{1,8}/
 // R9: чат-преамбули малих моделей — «озвучування завдання» перед відповіддю
 // («Ось оновлена чорнетка секції…», «Як технічний письменник, я створю…»,
@@ -138,6 +146,11 @@ const PROTECTED_HEADING = 'Призначення'
 const PROTECTED_START_RE = /^##\s+Призначення\s*$/
 const H2_RE = /^##\s/
 const H1_RE = /^#\s/
+const SIGNATURE_CALL_RE = /([`\w$.]{1,80})\([^()]{0,300}\)/g
+const NORMALIZED_SPACE_RE = /\s+/g
+const H2_HEADING_RE = /^##\s.+$/gm
+const TEST_SCENARIOS_HEADING = '## Сценарії використання'
+const BEHAVIOR_HEADING = '## Поведінка'
 
 /**
  * R9: зрізає провідні чат-преамбули й дубль назви секції з початку тексту.
@@ -169,7 +182,11 @@ function stripSection(text) {
     t = t.replace(FENCE_OPEN_RE, '').replace(FENCE_CLOSE_RE, '').trim()
   }
   t = t.replace(LEADING_HEADING_RE, '') // зрізати випадковий заголовок
-  return stripLeadingPreamble(t.trim()).trim()
+  return stripLeadingPreamble(t.trim())
+    .replaceAll(EMPTY_INLINE_CODE_SENTENCE_RE, '')
+    .replaceAll(PAREN_MDC_SENTENCE_RE, '')
+    .replaceAll(EMPTY_INLINE_CODE_RE, '')
+    .trim()
 }
 
 /**
@@ -181,7 +198,7 @@ function stripSection(text) {
  */
 function stripSignatures(text) {
   let t = text
-  for (let i = 0; i < 2; i++) t = t.replaceAll(/([`\w$.]{1,80})\([^()]{0,300}\)/g, '$1')
+  for (let i = 0; i < 2; i++) t = t.replaceAll(SIGNATURE_CALL_RE, '$1')
   return t
 }
 
@@ -424,6 +441,67 @@ export async function buildApiSection(facts, anchors, model, timeoutMs, temperat
   return [coveredBlock, gapDraft].filter(Boolean).join('\n')
 }
 
+/**
+ * Чи коментарі автора повністю покривають машинну документацію: header дає
+ * «Огляд», а змістовні описи всіх public API — відповідну секцію. У такому
+ * разі LLM не потрібна: текст зберігається дослівно для JS, Rust і Python.
+ * @param {object} facts факт-лист мовного екстрактора
+ * @returns {boolean} true, якщо можна зібрати документ без LLM
+ */
+export function hasCompleteCommentDocumentation(facts) {
+  return Boolean(facts.header?.trim()) && (facts.exports ?? []).every(exp => !isApiGap(exp))
+}
+
+/** Мінімальний розмір header, який може бути лише pointer-ом, а не наративом. */
+const SHORT_HEADER_CHARS = 240
+/** Один докладний public API може сам закрити короткий header-pointer. */
+const SUFFICIENT_SINGLE_API_CHARS = 160
+/** Сигнали потоку, який доцільно стисло звʼязати окремою «Поведінкою». */
+const BEHAVIOR_FLOW_RE =
+  /\b(?:await|Promise\.all|Semaphore|JoinSet|chunks|concurr|retry|queue|state|workflow|resolver|provider|catch|try|match)\b/i
+
+/**
+ * Вибирає гібридний режим для повністю прокоментованого source. Короткий
+ * header майже напевно є pointer-ом, а середній header разом із явним flow у
+ * коді потребує короткого LLM-доповнення. Детальний наратив лишається 0-LLM.
+ * @param {object} facts факт-лист мовного екстрактора
+ * @param {string} src вміст source-файлу
+ * @returns {'fallback'|'comment-only'|'comment+behavior'} режим генерації
+ */
+export function commentDocumentationMode(facts, src) {
+  if (!hasCompleteCommentDocumentation(facts)) return 'fallback'
+  const headerSize = facts.header.trim().replaceAll(NORMALIZED_SPACE_RE, ' ').length
+  const exports = facts.exports ?? []
+  const apiSize = exports
+    .map(exp => exp.desc?.replaceAll(NORMALIZED_SPACE_RE, ' ').length ?? 0)
+    .reduce((sum, size) => sum + size, 0)
+  // У маленькому модулі один ретельно описаний API уже є поведінковим
+  // контрактом. LLM тут найчастіше додає загальні фрази замість глибини.
+  if (headerSize < SHORT_HEADER_CHARS && exports.length === 1 && apiSize >= SUFFICIENT_SINGLE_API_CHARS) {
+    return 'comment-only'
+  }
+  if (headerSize < SHORT_HEADER_CHARS) return 'comment+behavior'
+  if (headerSize < 900 && BEHAVIOR_FLOW_RE.test(src)) return 'comment+behavior'
+  return 'comment-only'
+}
+
+/**
+ * Збирає документ лише з авторських коментарів і детермінованих фактів.
+ * @param {object} facts факт-лист мовного екстрактора
+ * @param {string|null} intent захищена секція «Призначення»
+ * @param {string} [behavior] додаткова LLM-секція «Поведінка» для comment+behavior режиму
+ */
+function commentOnlyDoc(facts, intent, behavior = '') {
+  const sections = {
+    overview: facts.header.trim(),
+    api: (facts.exports ?? []).map(exp => renderApiLine(exp)).join('\n'),
+    behavior,
+    scenarios: renderTestScenarios(facts.testScenarioFiles ?? []),
+    guarantees: guaranteesFromMarkers(facts)
+  }
+  return { md: insertProtected(assemble(basename(facts.relPath), sections), intent) }
+}
+
 /**
  * One-shot: один виклик LLM на весь документ (для unsupported-структур).
  * @param {object} facts факт-лист
@@ -437,7 +515,7 @@ async function oneShotDoc(facts, src, model, timeoutMs = LOCAL_TIMEOUT_MS, { int
   const text = await callLlm(oneShotMessages(facts, src), model, { timeoutMs })
   let md = stripSignatures(stripSection(text))
   if (!md.startsWith('#')) md = `# ${basename(facts.relPath)}\n\n${md}`
-  return { md: insertProtected(md + '\n', intent) }
+  return { md: insertProtected(insertTestScenarios(md + '\n', facts), intent) }
 }
 
 /**
@@ -451,6 +529,7 @@ function assemble(stem, sections) {
     ['overview', '## Огляд'],
     ['behavior', '## Поведінка'],
     ['api', '## Публічний API'],
+    ['scenarios', '## Сценарії використання'],
     ['guarantees', '## Гарантії поведінки']
   ]
   const parts = [`# ${stem}`]
@@ -461,6 +540,55 @@ function assemble(stem, sections) {
   return parts.join('\n\n') + '\n'
 }
 
+/**
+ * Видаляє H2-секцію з Markdown без regex з довільним тілом секції.
+ * @param {string} md зібраний Markdown-документ
+ * @param {string} heading точний H2-заголовок секції
+ * @returns {string} документ без секції
+ */
+function removeH2Section(md, heading) {
+  const lines = md.split('\n')
+  const start = lines.findIndex(line => line.trim() === heading)
+  if (start === -1) return md
+  const end = lines.findIndex((line, index) => index > start && H2_RE.test(line))
+  return [...lines.slice(0, start), ...lines.slice(end === -1 ? lines.length : end)].join('\n')
+}
+
+/**
+ * Повертає тіло H2-секції з Markdown без regex з довільним тілом секції.
+ * @param {string} md зібраний Markdown-документ
+ * @param {string} heading точний H2-заголовок секції
+ * @returns {string} тіло секції або порожній рядок
+ */
+function h2SectionBody(md, heading) {
+  const lines = md.split('\n')
+  const start = lines.findIndex(line => line.trim() === heading)
+  if (start === -1) return ''
+  const end = lines.findIndex((line, index) => index > start && H2_RE.test(line))
+  return lines
+    .slice(start + 1, end === -1 ? lines.length : end)
+    .join('\n')
+    .trim()
+}
+
+/**
+ * Додає test-сценарії до one-shot/batch-документа. Для unsupported мов основний
+ * Markdown ще повертає LLM, але test-секція лишається виключно JS-рендером.
+ * @param {string} md зібраний Markdown-документ
+ * @param {object} facts факт-лист із `testScenarioFiles`
+ * @returns {string} документ із детермінованою секцією сценаріїв
+ */
+export function insertTestScenarios(md, facts) {
+  const scenarios = renderTestScenarios(facts.testScenarioFiles ?? [])
+  if (!scenarios) return md
+  const withoutOld = removeH2Section(md, TEST_SCENARIOS_HEADING).trimEnd()
+  const section = `## Сценарії використання\n\n${scenarios}`
+  const guarantees = '\n\n## Гарантії поведінки'
+  const at = withoutOld.indexOf(guarantees)
+  if (at === -1) return `${withoutOld}\n\n${section}\n`
+  return `${withoutOld.slice(0, at)}\n\n${section}${withoutOld.slice(at)}\n`
+}
+
 /**
  * Orchestrated: N окремих LLM-викликів, по одному на секцію.
  * Код потрапляє лише в `behavior`; решта секцій — на мінімальному факт-листі.
@@ -478,10 +606,21 @@ async function orchestratedDoc(
   timeoutMs,
   { anchors = null, temperature = 0.2, intent = null } = {}
 ) {
+  const commentMode = commentDocumentationMode(facts, src)
+  if (commentMode === 'comment-only') return commentOnlyDoc(facts, intent)
+  if (commentMode === 'comment+behavior') {
+    const [behaviorPrompt] = sectionMessages(facts, src, anchors, intent, { complementaryBehavior: true })
+    const behavior = stripSignatures(
+      stripSection(await callLlm(behaviorPrompt.messages, model, { timeoutMs, temperature }))
+    )
+    return { md: commentOnlyDoc(facts, intent, CRITIC_NONE_RE.test(behavior.trim()) ? '' : behavior).md }
+  }
   const sections = {}
   const anc = anchors ?? extractAnchors(src)
   // E3: «Гарантії» — детермінований шаблон з markers (0 LLM-запитів, 0 generic-фраз)
   sections.guarantees = guaranteesFromMarkers(facts)
+  // Test/spec назви рендеряться JS-ом дослівно, а не потрапляють у LLM prompt.
+  sections.scenarios = renderTestScenarios(facts.testScenarioFiles ?? [])
   // Спершу Поведінка — єдина секція з кодом (sectionMessages повертає лише її)
   for (const s of sectionMessages(facts, src, anc, intent)) {
     sections[s.key] = stripSignatures(stripSection(await callLlm(s.messages, model, { timeoutMs, temperature })))
@@ -502,6 +641,27 @@ async function orchestratedDoc(
   return { md: insertProtected(assemble(basename(facts.relPath), sections), intent) }
 }
 
+/**
+ * Semantic evidence для judge: лише source-код; test-сценарії формує JS.
+ * @param {string} src source-код
+ * @returns {string} evidence для judge
+ */
+function semanticEvidence(src) {
+  return src
+}
+
+/**
+ * Витягує LLM-секцію «Поведінка» для вузького semantic judge. Авторські
+ * «Огляд»/API не оцінюються моделлю і не можуть бути нею переписані.
+ * @param {string} md зібраний Markdown-документ
+ * @returns {string} мінімальний документ з однією секцією або порожній рядок
+ */
+function behaviorOnlyDocument(md) {
+  const body = h2SectionBody(md, BEHAVIOR_HEADING)
+  return body ? `# Поведінка\n\n## Поведінка\n\n${body}\n` : ''
+  return match ? `# Поведінка\n\n## Поведінка\n\n${match[1].trim()}\n` : ''
+}
+
 /**
  * №6 — judge-refine: суддя назвав конкретні неточності (`judge.reason`) — один
  * локальний refine-прохід замість лише маркування degraded. Приймаємо виправлену
@@ -520,13 +680,13 @@ async function judgeRefinePass(r, judge, { facts, anchors, src, score, model, ch
   if (!fixed.startsWith('#')) fixed = `# ${basename(facts.relPath)}\n\n${fixed}`
   const fixedMd = insertProtected(fixed + '\n', intentBody)
   // Guard 1: рерайт не має губити секції (малі моделі інколи повертають фрагмент)
-  const origHeadings = r.md.match(/^##\s.+$/gm) ?? []
+  const origHeadings = r.md.match(H2_HEADING_RE) ?? []
   if (origHeadings.some(h => !fixedMd.includes(h))) return null
   // Guard 2: det-score не має падати
   const sFixed = scoreDoc(fixedMd, facts, { anchors, src })
   if (sFixed.score < score) return null
   // Guard 3: повторний суддя (той самий scope: inaccurate)
-  const judge2 = { ...(await judgeDoc(src, fixedMd, { chain })), model: JUDGE_MODEL }
+  const judge2 = { ...(await judgeDoc(semanticEvidence(src), fixedMd, { chain })), model: JUDGE_MODEL }
   if (judgeFailsDoc(judge2)) return null
   return { md: fixedMd, score: sFixed.score, issues: sFixed.issues, judge: judge2 }
 }
@@ -541,7 +701,7 @@ async function judgeRefinePass(r, judge, { facts, anchors, src, score, model, ch
 async function runJudgeGate({ r, score, issues, facts, anchors, src, model, chain }) {
   let judge = null
   try {
-    judge = { ...(await judgeDoc(src, r.md, { chain })), model: JUDGE_MODEL }
+    judge = { ...(await judgeDoc(semanticEvidence(src, facts), r.md, { chain })), model: JUDGE_MODEL }
     // №6: суддя назвав конкретні неточності → один локальний refine-прохід
     // (опт-аут: N_CURSOR_DOCGEN_JUDGE_REFINE=0). Прийнято лише коли всі
     // guard-и judgeRefinePass пройдені; інакше — degraded, як раніше.
@@ -610,10 +770,13 @@ function srcTokenBudget() {
  * (js/mjs/ts — lang-js, `.rs` — lang-rust; whole-file `unsupported`-fallback, якщо
  * екстрактора для розширення нема).
  * @param {string} file абсолютний шлях джерела
+ * @param {ReturnType<typeof buildTestEvidenceIndex>|null} [testIndex] source↔tests index
  * @returns {Promise<{ src: string, estTokens: number, ext: string, langExtractors: Map<string, object>, facts: object }>} усе потрібне обом callers перед LLM-викликом
  */
-async function loadSrcAndFacts(file) {
+async function loadSrcAndFacts(file, testIndex = null) {
   const src = readFileSync(file, 'utf8')
+  const evidenceIndex = testIndex ?? (existsSync(file) ? buildTestEvidenceIndex(process.cwd()) : null)
+  const testEvidence = evidenceIndex ? testEvidenceForSource(file, evidenceIndex) : { files: [] }
   const estTokens = Math.round(Buffer.byteLength(src, 'utf8') / 4)
   const budget = srcTokenBudget()
   if (estTokens > budget) {
@@ -623,7 +786,7 @@ async function loadSrcAndFacts(file) {
   }
   const langExtractors = await loadDocFilesExtractors(process.cwd())
   const ext = `.${file.split('.').pop()}`.toLowerCase()
-  const facts = langExtractors.get(ext)?.extractFacts?.(src, file) ?? {
+  const extractedFacts = langExtractors.get(ext)?.extractFacts?.(src, file) ?? {
     relPath: file,
     lang: ext.slice(1),
     unsupported: true,
@@ -632,6 +795,10 @@ async function loadSrcAndFacts(file) {
     imports: {},
     markers: {}
   }
+  const facts = {
+    ...extractedFacts,
+    testScenarioFiles: testEvidence.files
+  }
   return { src, estTokens, ext, langExtractors, facts }
 }
 
@@ -674,7 +841,7 @@ function finishUnsupported(r, { t0, model, chainExtra }) {
  * з вищою температурою (best-of-2); якщо й він не допоміг — результат
  * позначається `degraded`, рішення про перегенерацію приймає batch/користувач.
  * @param {string} file абсолютний шлях джерела
- * @param {{ model?: string, threshold?: number, existingMd?: string|null, chainFactory?: typeof startChain, deadlineAt?: number|null }} [opts] model-id, поріг degraded, наявна дока (для збереження захищеної секції), фабрика ланцюжка (інжект для тестів), deadlineAt — мʼякий дедлайн fix-pipeline (epoch ms): per-call таймаути ріжуться під залишок бюджету, вичерпаний бюджет обриває генерацію transient-помилкою
+ * @param {{ model?: string, threshold?: number, existingMd?: string|null, chainFactory?: typeof startChain, deadlineAt?: number|null, testIndex?: ReturnType<typeof buildTestEvidenceIndex>|null }} [opts] model-id, поріг degraded, наявна дока (для збереження захищеної секції), фабрика ланцюжка (інжект для тестів), deadlineAt — мʼякий дедлайн fix-pipeline (epoch ms): per-call таймаути ріжуться під залишок бюджету, вичерпаний бюджет обриває генерацію transient-помилкою; testIndex — спільний source↔tests index батчу
  * @returns {{ md: string, ms: number, llmMs: number, llmCalls: number, score: number|null, issues: string[], degraded: boolean, model: string }} документ і метадані генерації (ms — увесь файл; llmMs/llmCalls — лише LLM; решта ms — оркестрація)
  */
 export async function generateDoc(
@@ -684,11 +851,12 @@ export async function generateDoc(
     threshold = QUALITY_THRESHOLD,
     existingMd = null,
     chainFactory = startChain,
-    deadlineAt = null
+    deadlineAt = null,
+    testIndex = null
   } = {}
 ) {
   // Guard ДО створення ланцюжка: skip без LLM — не задача.
-  const { src, estTokens, ext, langExtractors, facts } = await loadSrcAndFacts(file)
+  const { src, estTokens, ext, langExtractors, facts } = await loadSrcAndFacts(file, testIndex)
   const t0 = Date.now()
   llmMeter = { calls: 0, ms: 0 }
   const chain = chainFactory({ kind: 'doc-generate', unit: facts.relPath, cwd: process.cwd() })
@@ -717,6 +885,7 @@ export async function generateDoc(
     // Варіант B: захищена секція «Призначення» з наявної доки — зберегти й подати як контекст
     const intent = existingMd ? splitProtected(existingMd).body : null
     const anchors = facts.unsupported ? null : extractAnchors(src)
+    const commentMode = commentDocumentationMode(facts, src)
     const promptSrc = resolvePromptSrc({ facts, estTokens, langExtractors, ext, src, file })
     let r = facts.unsupported
       ? await oneShotDoc(facts, src, model, LOCAL_TIMEOUT_MS, { intent })
@@ -732,6 +901,49 @@ export async function generateDoc(
     // Stage 2.5: детермінований скоринг (0 токенів)
     let { score, issues } = scoreDoc(r.md, facts, { anchors, src })
 
+    // Авторські header/API-коментарі — уже джерело істини. Для comment-only
+    // LLM не запускається зовсім; comment+behavior судить лише LLM-секцію.
+    if (commentMode === 'comment-only') {
+      chainExtra.score = score
+      chainExtra.degraded = false
+      return {
+        ...r,
+        ms: Date.now() - t0,
+        llmMs: llmMeter.ms,
+        llmCalls: llmMeter.calls,
+        score,
+        issues,
+        degraded: false,
+        model
+      }
+    }
+
+    if (commentMode === 'comment+behavior') {
+      const behaviorDoc = behaviorOnlyDocument(r.md)
+      let judge = null
+      if (JUDGE_ENABLED && behaviorDoc) {
+        judge = { ...(await judgeDoc(semanticEvidence(src), behaviorDoc, { chain })), model: JUDGE_MODEL }
+        if (judgeFailsDoc(judge)) {
+          r = commentOnlyDoc(facts, intent)
+          ;({ score, issues } = scoreDoc(r.md, facts, { anchors, src }))
+          issues.push('behavior-judge-removed')
+        }
+      }
+      chainExtra.score = score
+      chainExtra.degraded = false
+      return {
+        ...r,
+        ms: Date.now() - t0,
+        llmMs: llmMeter.ms,
+        llmCalls: llmMeter.calls,
+        score,
+        issues,
+        judge,
+        degraded: false,
+        model
+      }
+    }
+
     // E4: best-of-2 — один retry з вищою температурою, det-вибір кращого
     if (score < threshold && env.N_CURSOR_DOCGEN_BEST_OF !== '0') {
       try {
@@ -786,14 +998,21 @@ export async function generateDoc(
  * всі файли разом). Кидає ту саму помилку pre-send guard, що й `generateDoc`
  * (класифікується `permanent` у batch-оркестраторі — skip, не помилка прогону).
  * @param {string} file абсолютний шлях джерела
- * @param {{ existingMd?: string|null }} [opts] наявна дока (для захищеної секції «Призначення»)
- * @returns {Promise<{ facts: object, anchors: object|null, src: string, messages: Array<{role:string,content:string}>, intent: string|null }>} усе потрібне для item-у batch-у й пізнішого фінішу
+ * @param {{ existingMd?: string|null, testIndex?: ReturnType<typeof buildTestEvidenceIndex>|null }} [opts] наявна дока (для захищеної секції «Призначення») і спільний source↔tests index
+ * @returns {Promise<{ facts: object, anchors: object|null, src: string, mode: string, messages: Array<{role:string,content:string}>, intent: string|null }>} усе потрібне для item-у batch-у й пізнішого фінішу; `comment-only` повертає порожні messages
  */
-export async function prepareBatchItem(file, { existingMd = null } = {}) {
-  const { src, facts } = await loadSrcAndFacts(file)
+export async function prepareBatchItem(file, { existingMd = null, testIndex = null } = {}) {
+  const { src, facts } = await loadSrcAndFacts(file, testIndex)
   const anchors = facts.unsupported ? null : extractAnchors(src)
   const intent = existingMd ? splitProtected(existingMd).body : null
-  return { facts, anchors, src, messages: oneShotMessages(facts, src), intent }
+  const mode = facts.unsupported ? 'fallback' : commentDocumentationMode(facts, src)
+  const messages =
+    mode === 'comment-only'
+      ? []
+      : mode === 'comment+behavior'
+        ? sectionMessages(facts, src, anchors, intent, { complementaryBehavior: true })[0].messages
+        : oneShotMessages(facts, src)
+  return { facts, anchors, src, mode, messages, intent }
 }
 
 /**
@@ -803,13 +1022,28 @@ export async function prepareBatchItem(file, { existingMd = null } = {}) {
  * викликається (мінімальний обсяг T8 — генерація; judge лишається опційним
  * розширенням послідовного шляху).
  * @param {string} text сирий текст відповіді моделі для цього item-у
- * @param {{ facts: object, anchors: object|null, src: string, intent: string|null, model: string, threshold?: number }} ctx контекст item-у (з `prepareBatchItem`)
+ * @param {{ facts: object, anchors: object|null, src: string, intent: string|null, model: string, threshold?: number, mode?: string }} ctx контекст item-у (з `prepareBatchItem`)
  * @returns {{ md: string, score: number|null, issues: string[], degraded: boolean, model: string }} результат генерації для штампу/запису
  */
-export function finishBatchItem(text, { facts, anchors, src, intent, model, threshold = QUALITY_THRESHOLD }) {
+export function finishBatchItem(
+  text,
+  { facts, anchors, src, intent, model, threshold = QUALITY_THRESHOLD, mode = null }
+) {
+  const commentMode = mode ?? (facts.unsupported ? 'fallback' : commentDocumentationMode(facts, src))
+  if (commentMode === 'comment-only') {
+    const md = commentOnlyDoc(facts, intent).md
+    const { score, issues } = scoreDoc(md, facts, { anchors, src })
+    return { md, score, issues, degraded: false, model }
+  }
+  if (commentMode === 'comment+behavior') {
+    const behavior = stripSignatures(stripSection(text))
+    const md = commentOnlyDoc(facts, intent, CRITIC_NONE_RE.test(behavior.trim()) ? '' : behavior).md
+    const { score, issues } = scoreDoc(md, facts, { anchors, src })
+    return { md, score, issues, degraded: false, model }
+  }
   let md = stripSignatures(stripSection(text))
   if (!md.startsWith('#')) md = `# ${basename(facts.relPath)}\n\n${md}`
-  md = insertProtected(md + '\n', intent)
+  md = insertProtected(insertTestScenarios(md + '\n', facts), intent)
   if (facts.unsupported) {
     const refusal = detectRefusalFiller(splitProtected(md).without)
     return {

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

@@ -3,33 +3,35 @@ type: JS Module
 title: main.mjs
 resource: npm/rules/doc-files/docgen-prompts/main.mjs
 docgen:
-  crc: 8cb3a892
-  model: openai-codex/gpt-5.5
-  tier: cloud-avg
+  crc: d09eacad
+  model: openai-codex/gpt-5.4-mini
+  tier: cloud-min
   score: 100
-  issues: judge-refine:kept-original,judge:inaccurate:0.99
+  issues: judge-refine:kept-original,judge:inaccurate:0.98
   judgeModel: openai-codex/gpt-5.4-mini
 ---
 
 ## Огляд
 
-Файл формує промпти й детерміновані фрагменти для генерації поведінкової документації: `STYLE` задає спільний тон, `sectionMessages`, `overviewMessages`, `criticMessages`, `refineMessages`, `oneShotMessages` і `judgeRefineMessages` готують повідомлення для різних етапів, `isApiGap`, `renderApiLine` та `apiGapMessages` висвітлюють прогалини API, а `guaranteesFromMarkers` і `buildUnitDigest` стискають контекст до контрольованого обсягу `UNIT_DIGEST_TOKENS`. Файл існує як текстовий шар оркестратора документації, щоб підтримувати лаконічний стиль, узгоджувати очікування між етапами генерації та зменшувати ризик вигаданих тверджень. У межах одного прогону використовує кешування для повторного використання вже підготовлених результатів.
+`STYLE` задає спільний тон і межі викладу, а `sectionMessages` і `overviewMessages` узгоджують текст секції з уже відомими фактами. `isApiGap`, `apiGapMessages` і `renderApiLine` допомагають окремо фіксувати прогалини в API, щоб опис лишався чесним і не приписував зайвого. `criticMessages`, `refineMessages`, `oneShotMessages` і `judgeRefineMessages` підтримують послідовне доопрацювання одного й того ж змісту, а `guaranteesFromMarkers` і `UNIT_DIGEST_TOKENS` тримають описи в межах підтверджених маркерів і зведених одиниць.
 
 ## Поведінка
 
-STYLE задає спільні правила тону й форми для промптів, щоб усі згенеровані секції лишалися лаконічними, поведінковими та без технічного шуму.
+STYLE задає спільний тон і межі для всього генератора: з нього випливають правила лаконічності, безпечної опори на факти та узгодженості між секціями.
 
-Основний потік генерації розділяє документацію на незалежні кроки. sectionMessages формує запит лише для секції «Поведінка» з мінімальним контекстом: фактами про файл, релевантними анкорами, захищеним «Призначенням» і, за потреби, стислим представленням коду. Після отримання готової «Поведінки» overviewMessages створює «Огляд» уже з неї, а не напряму з коду, щоб підсумок спирався на підтверджений опис поведінки.
+sectionMessages збирає мінімальний контекст для поведінкових секцій і запускає основний потік: factsSummary дає стислий факт-витяг, anchorsBlock додає лише потрібні анкори, intentContext підключає захищене «Призначення» як read-only фон, а msgs поєднує все у формат одного LLM-виклику. Саме тут зароджується текст секції «Поведінка», і саме тут враховується позначка про complementarity, коли LLM має доповнювати прогалини, а не переписувати вже відоме.
 
-Публічний API обробляється гібридно без зайвого LLM-переписування. isApiGap визначає, які експорти не мають змістовного опису. Для покритих описом експортів renderApiLine повертає дослівний рядок документації, зберігаючи авторський текст. Для прогалин apiGapMessages формує окремий вузький запит тільки по відсутніх описах, щоб модель не торкалася вже надійних JSDoc-фрагментів.
+isApiGap відсікає експорти, які вже мають змістовний JSDoc, від тих, що потребують синтезу; далі цей поділ живить окремий шлях для API, щоб не змішувати покритий текст із прогалинами. renderApiLine використовує лише вже описані експорти і переносить їх у публічний список без перефразування, а apiGapMessages працює тільки з невкритими експортами, щоб LLM не контактував із уже зафіксованим авторським формулюванням.
 
-Якість машинних секцій підсилюється окремим циклом перевірки. criticMessages готує запит до критика, який має знайти конкретні дефекти або підтвердити їх відсутність. refineMessages використовує ці зауваження для переписування чорнетки без зміни призначення секції. judgeRefineMessages виконує точкове доопрацювання документа за причиною від судді, коли потрібно виправити конкретне хибне твердження замість просто позначити результат як погіршений.
+overviewMessages формує завершальний узагальнювальний крок: бере вже написану «Поведінку», підкріплює її factsSummary та, за потреби, intentContext, і на цій основі просить Огляд. Це замикає порядок секцій так, щоб Огляд узгоджувався з готовим змістом, а не вигадувався з сирих фактів.
 
-guaranteesFromMarkers створює «Гарантії поведінки» детерміновано з маркерів факт-листа, без LLM-запиту. Це відокремлює формальні гарантії від вільного тексту й зменшує ризик вигаданих тверджень.
+criticMessages і refineMessages працюють парою як цикл якості для окремих секцій: критик звіряє чорнетку з facts і anchorsBlock та повертає конкретні issues, після чого refineMessages переписує текст тільки на підставі цих зауважень. Завдяки цьому правки залишаються локальними й не розмивають уже добрі частини секції.
 
-oneShotMessages лишається базовим одноетапним сценарієм для порівняння з секційним потоком. UNIT_DIGEST_TOKENS задає межу компактного представлення великих файлів, а buildUnitDigest перетворює набір юнітів на стислий дайджест, щоб промпт зберігав фокус на структурі й поведінці замість перевантаження сирим кодом.
+guaranteesFromMarkers не входить у LLM-потік: він детерміновано виводить гарантовані властивості з facts.markers і слугує стабільним шаром, який не залежить від генеративної варіативності. Це тримає критичні твердження поза ризиком галюцинацій.
 
-Файл не виконує власних записів у файлову систему чи базу даних: результати всіх публічних функцій повертаються як текстові секції, рядки або масиви повідомлень для подальшої обробки зовнішнім оркестратором. Кешування використовується лише в межах поточного прогону.
+oneShotMessages є базовою точкою порівняння для одного суцільного LLM-запиту: до нього потрапляють facts і src без розбиття на секції. buildUnitDigest підміняє сирий src компактним структурним дайджестом, коли великий файл починає розмивати фокус моделі; UNIT_DIGEST_TOKENS обмежує цей режим, щоб зберігати промпт коротким і передбачуваним.
+
+judgeRefineMessages підхоплює фінальне локальне доопрацювання після judge-перевірки: reason від судді стає єдиною опорою для точкового виправлення doc-тексту без залучення захищеного «Призначення». Увесь потік спирається на спільний кеш у межах одного прогону, щоб повторні звернення до тих самих даних не змінювали результат і не множили витрати.
 
 ## Публічний API
 
@@ -71,6 +73,10 @@ LLM-судді (замість лише маркування degraded). Судд
 хибне (`reason`) — мала модель добре виправляє точкові твердження, коли їй
 сказано, які саме.
 
+## Сценарії використання
+
+- `npm/rules/doc-files/docgen-prompts/tests/docgen-prompts.test.mjs` (sectionMessages — Огляд більше не тут (R3); guaranteesFromMarkers — лише file-local твердження) — не повертає секцію overview; Поведінка обмежена експортованими іменами (R6); Поведінка не отримує test evidence: сценарії рендерить JS окремою секцією; гібридний режим просить доповнити comments лише відсутнім потоком; fail-safe маркер не обіцяє, що всі помилки лишаються всередині модуля; ще 10
+
 ## Гарантії поведінки
 
 - Власних операцій запису (ФС/БД) у файлі немає; виклики імпортованих модулів можуть писати.

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\`\`\``
   )
 }