# docgen-scan.mjs

## Огляд

`docgen scanner` обходить проєкт, щоб створити JSON-список кодових файлів, розташованих у теці `docs/` поряд із джерелом. Цей список використовується іншими скілами для генерації документації. Інструмент забезпечує детермінований обхід проєкту та відстежує наявність файлів, не використовуючи мережеві ресурси чи LLM.

## Поведінка

- `isSourceFile`: Перевіряє, чи файл є джерелом коду, враховуючи розширення та тестові файли.
- `docPathForSource`: Генерує шлях до файлу документації для заданого джерела, враховуючи відносні шляхи.
- `scanForDocgen`: Рекурсивно обходить дерево проєкту, визначаючи кодові файли, які потрібно документувати, та їх відповідні шляхи до документації.
- `slugForModule`: Генерує унікальний slug для модуля на основі його відносного шляху.
- `findModuleRoots`: Знаходить абсолютні шляхи коренів модулів проєкту.
- `nearestModuleRoot`: Знаходить найближчий модуль-предок для заданого файлу.
- `scanForModules`: Лістить модулі проєкту, визначаючи їхні члени (sourcePath-и) та шляхи до документації.
- `resolveRoot`: Визначає абсолютний корінь проєкту на основі аргументів командного рядка.
- `runDocgenScanCli`: Запускає сканування docgen як CLI, виводить JSON-масив у stdout та повертає код виходу.
- `runDocgenModulesCli`: Запускає сканування модулів docgen як CLI, виводить JSON-масив у stdout та повертає код виходу.

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

- isSourceFile — Визначає, чи є файл кодовим джерелом для створення документації.
- docPathForSource — Генерує шлях до md-файлу, пов'язаний з кодовим файлом.
- scanForDocgen — Рекурсивно обстежує структуру проєкту, виявляючи файли для документування.
- slugForModule — Створює унікальний ідентифікатор (slug) для модуля на основі його шляху.
- findModuleRoots — Знаходить корені модулів, визначаючи директорії з файлом `package.json`.
- nearestModuleRoot — Визначає найближчий модуль-предок для заданого файлу.
- scanForModules — Створює список логічних модулів проєкту, включаючи файли та інформацію про них.
- resolveRoot — Встановлює базову директорію для сканування, використовуючи аргумент командного рядка або поточну директорію.
- runDocgenScanCli — Запускає сканування для виявлення файлів документації та виводить результат у форматі JSON.
- runDocgenModulesCli — Запускає сканування модулів та виводить результат у форматі JSON.

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

- `isSourceFile` повертає `true`, якщо вказаний шлях до файлу є джерелом коду.
- `isSourceFile` повертає `false` в іншому випадку.
- `docPathForSource` повертає шлях до відповідної папки `docs/` для вказаного джерела.
- `scanForDocgen` повертає JSON-список шляхів до кодових файлів, які потрібно обробити.
- `scanForDocgen` встановлює прапор `exists` у випадку, якщо файл або папка вже існують.
- `slugForModule` повертає унікальний URL-шлях для модуля.
- `findModuleRoots` повертає список кореневих модулів проєкту.
- `nearestModuleRoot` повертає найближчий кореневий модуль до вказаного шляху.
- `scanForModules` повертає список модулів проєкту.
- `resolveRoot` повертає кореневу папку проєкту.
- `runDocgenScanCli` запускає процес сканування для `docgen`.
- `runDocgenModulesCli` запускає процес сканування для модулів.
- У разі невдачі повертається `false` та `null`.
-
