---
docgen:
  source: npm/rules/npm-module/js/header_doc_pointer.mjs
  crc: 9058c4ea
---

# header_doc_pointer.mjs

## Огляд

Концерн правила `npm-module`, що закріплює контракт між `docs/<stem>.md` і module-level JSDoc у скриптах правил і скілів. Якщо файл вже описано у `docs/<stem>.md` — наратив у заголовному коментарі файлу є дублюванням і заборонений. Якщо `docs` немає — header залишається єдиним джерелом опису поведінки і жодних обмежень немає.

## Поведінка

1. Сканує всі `.mjs`-файли (крім `.test.mjs`) у `npm/rules/*/js/` та `npm/skills/*/js/`.
2. Для кожного файлу перевіряє наявність `docs/<stem>.md` поруч із `js/`.
3. Якщо `docs/<stem>.md` **відсутній** — пропускає файл: перевірка не застосовується.
4. Якщо `docs/<stem>.md` **присутній** — знаходить module-level JSDoc (перший `/** ... */` до першого `import`/`export` на початку рядка).
5. Рахує непорожні змістовні рядки блоку (після зрізання відступу `*`). Більше одного → порушення.

Допустимі форми при наявних docs:

- відсутній module-level JSDoc (0 рядків)
- `/** @see ./docs/<stem>.md */` (1 рядок)
- `/** Контракт: ./docs/<stem>.md */` (1 рядок)

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

- Файли без `docs/`-відповідника повністю ігноруються — перевірка не створює обмежень до того, як docgen запишеться.
- Якщо у файлі немає жодного module-level JSDoc — перевірка проходить.
- Тестові файли (`*.test.mjs`) не скануються.
- Підкаталоги `tests/`, `data/`, `templates/` у `js/` не скануються (discovery бере лише `*.mjs` безпосередньо в `js/`, не рекурсивно).
