---
docgen:
  source: npm/rules/doc-files/js/docgen-crc.mjs
  crc: 54e8e12b
---

# docgen-crc

## Огляд

Детермінований маркер актуальності файлових док: контрольна сума джерела у frontmatter плюс опційний degraded-маркер якості. Єдине джерело правди про «дока свіжа/застаріла/неякісна» для генерації, перевірок і хуків.

## Поведінка

1. Контрольна сума обчислюється з байтів джерела і записується у машинний frontmatter доки разом зі шляхом джерела; розбіжність суми з поточним джерелом (або відсутність доки) означає застарілість.
2. Якщо генерація не дотягнула до порогу якості, frontmatter додатково несе оцінку (`score`) і коди проблем (`issues`); коди нормалізуються до YAML-безпечних (без пробілів, обмежена кількість), а старі доки без цих полів лишаються валідними.
3. Поріг degraded — `70`, override через `N_CURSOR_DOC_FILES_THRESHOLD`.
4. Перештампування знімає наявний frontmatter і ставить свіжий, не торкаючись тіла документа; якість при цьому передається явно — без неї поля якості зникають.

## Публічний API

- `crc32` — контрольна сума вмісту в hex.
- `staleness` — стан доки відносно джерела: `missing` / `crc-mismatch` / свіжа.
- `parseDocFrontmatter` / `buildDocFrontmatter` / `stampDoc` — читання і (пере)штампування машинного блока.
- `readDocCrc` / `readDocQuality` — точкове читання суми та якості з доки.
- `QUALITY_THRESHOLD` — чинний поріг degraded.

## Гарантії поведінки

- Сума не залежить від git-стану: rebase, гілки й незакомічені зміни на неї не впливають.
- Frontmatter — єдиний машинний виняток із правила «чистий Markdown»; тіло доки модуль не редагує.
- Відсутні поля якості читаються як «не оцінено» (`score: null`), а не як нуль.
