---
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`) замість винятку.