---
type: JS Module
title: docgen-scan.mjs
resource: npm/rules/doc-files/js/docgen-scan.mjs
docgen:
  crc: f01465d8
  model: omlx/gemma-4-e4b-it-OptiQ-4bit
  score: 100
---

## Огляд

Модуль аналізує кодову базу та пов'язану з нею документацію. Він визначає, які файли є джерелами за допомогою `isSourceFile` та знаходить відповідні шляхи документації за допомогою `docPathForSource`. Модуль перевіряє, чи не залишилися без зв'язку (сиротами) документи, використовуючи `scanOrphanedDocs`, та сканує файли документації за допомогою `scanForDocFiles`. Для роботи з кореневими каталогами використовується `resolveRoot`. Усі операції виконуються з механізмом перехоплення помилок (fail-safe), при цьому при певних збоях повертається `null` замість викидання винятків.

## Поведінка

isSourceFile визначає, чи є ім'я файлу кодовим джерелом для документування.
docPathForSource обчислює шлях до відповідного MD-документа для заданого кодового файлу.
isDocCandidate визначає, чи підлягає певний файл документуванню, враховуючи розширення, статус тесту та ігнорування.
describeFile описує кодовий файл, надаючи його шлях, шлях до документації та стан застарілості.
scanOrphanedDocs знаходить MD-документи, які посилаються на кодові файли, що більше не існують.
scanForDocFiles рекурсивно обходить дерево і повертає список кодових файлів із їхнім станом застарілості, відфільтрований за ігноруванням Git.
resolveRoot парсить аргументи для визначення абсолютного кореня обходу, використовуючи поточну робочу директорію за замовчуванням.
runDocFilesScanCli сканує дерево і друкує JSON-масив усіх кодових файлів зі станом застарілості.
runDocFilesCheckCli виконує перевірку застарілості, підтримуючи режими для перевірки одного файлу, Git-гейту або звітів про знижену якість.

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

isSourceFile — визначає, чи є файл кодовим джерелом для створення документації.
docPathForSource — визначає шлях до відповідного MD-документа, розміщений у теці `docs/` відносно коду.
isDocCandidate — вирішує, чи повинен кодовий файл бути документований: має правильне розширення, не є тестом, не ігнорується та не є системним документом.
describeFile — надає опис кодового файлу, включаючи його шлях, шлях до документації та статус застарілості.
scanOrphanedDocs — шукає документи, які посилаються на кодові файли, що більше не існують, перевіряючи лише згенеровані файли.
scanForDocFiles — рекурсивно збирає всі кодові файли з дерева, визначаючи їхній статус застарілості, і відсіюючи ті, що ігноруються через `.gitignore`.
resolveRoot — встановлює кореневу директорію для сканування, використовуючи аргумент командного рядка або поточну робочу директорію.
runDocFilesScanCli — сканує дерево та виводить JSON-масив усіх кодових файлів зі статусом застарілості, дозволяючи фільтрувати лише застарілі або всі файли.
runDocFilesCheckCli — виконує перевірку застарілості для використання у хуках та командному інтерфейсі.

Режими:
--hook — перевіряє один файл, отриманий з JSON через стандартний ввід.
--git — порівнює файли у `git diff` та блокує процес, якщо знайдено більше за встановлений поріг застарілих файлів.
--degraded — виводить звіт про документи з низьким показником якості.
<paths…> — обробляє лише вказані шляхи-джерела.

Вихідний код 2 — вказує на знаходження застарілих файлів (для блокування хука).
Вихідний код 0 — вказує на відсутність застарілих файлів або проходження перевірки згідно з порогом.

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

- Read-only: не виконує операцій запису (ФС/БД).
- Перехоплює помилки і не пропускає винятків назовні (fail-safe).
- За певних помилок повертає порожнє значення (напр. `null`) замість винятку.
