--- type: JS Module title: main.mjs resource: npm/rules/doc-files/docgen-scan/main.mjs docgen: crc: 85fe01bc model: openai-codex/gpt-5.5 tier: cloud-avg score: 100 issues: judge:error judgeModel: openai-codex/gpt-5.4-mini --- ## Огляд Файл знаходить кодові файли, для яких має існувати file-level Markdown-документація в сусідній теці `docs/`, і визначає, чи ця документація відсутня або застаріла. Він також виявляє згенеровані документи, що втратили відповідний source-файл, і подає результати через POSIX-шляхи від кореня. ## Поведінка `resolveRoot` визначає абсолютний корінь обходу з аргументів запуску або поточної директорії. Від цього кореня далі беруться плагінні розширення кодових файлів, правила пропуску шляхів і відносні шляхи результатів. `scanForDocFiles` обходить дерево від кореня, відсіює некодові, тестові, ігноровані та system-wide docs-шляхи, а для кожного кандидата делегує оцінку документації в `describeFile`. Результатом є перелік кодових файлів із шляхом до очікуваної документації та ознакою, чи потрібне оновлення. `isSourceFile` є спільним фільтром типів файлів: кодовими вважаються лише розширення, надані активними lang-плагінами. Ядро не має власного вбудованого списку розширень, тому без відповідних contributions файл не стає кандидатом на документацію. `isDocCandidate` застосовує ті самі правила придатності для одного відносного шляху: файл має бути кодовим джерелом, не бути тестом, не лежати в ігнорованому дереві та не належати до кореневого system-wide docs layout. Це дає точкову перевірку тим самим критеріям, які масово використовує сканування. `docPathForSource` задає єдине правило розміщення file-level документації: Markdown-файл у сусідній теці `docs/` з іменем за stem джерела. Простір шляхів зберігається: відносне джерело дає відносний шлях документації, абсолютне — абсолютний. `describeFile` порівнює кодовий файл з очікуваним Markdown-документом, визначеним через `docPathForSource`. Якщо документа немає або збережений CRC не відповідає джерелу, файл позначається як застарілий. Якщо документ існує, але не має `docgen`-CRC у frontmatter, він вважається ручною документацією: така документація не позначається як застаріла й не має мовчки перезаписуватися звичайною генерацією. `scanOrphanedDocs` рухається у зворотному напрямку: шукає згенеровані Markdown-документи з прив’язкою до resource і CRC, для яких відповідний source-файл уже відсутній. Directory Index-документи та ручні документи без resource або CRC не входять до результату. Усі результати сканування подаються як posix-шляхи від кореня, щоб подальші команди могли однаково працювати з кандидатами, застарілими документами та сирітськими файлами незалежно від платформи. Файл сам не записує зміни: він лише класифікує джерела й документацію, а частину безпечних ситуацій обробляє fail-safe без зупинки потоку. ## Публічний API - isSourceFile — Чи є файл кодовим джерелом для документування. Розширення декларують ЛИШЕ `doc-files.extensions@1` contributions активних lang-плагінів (js/mjs/ts/vue дає `@7n/rules-lang-js`, .rs/.py — lang-rust/lang-python); у ядрі вбудованих розширень немає (фаза 5b spec lang-plugins-extraction, переведено на slot bus Фазою 2 spec 2026-07-27-universal-plugin-slots-lang-php-extraction). - docPathForSource — Обчислює шлях md-документа для кодового файлу: тека `docs/` поряд із джерелом. Якщо `sourcePath` відносний, `docPath` теж відносний; якщо абсолютний — абсолютний. - isDocCandidate — Чи кодовий файл `relPath` (posix, від кореня) підлягає документуванню: правильне розширення, не тест, не в ignore-дереві, не кореневий system-wide docs. - describeFile — Описує один кодовий файл: шлях джерела, шлях доки, стан застарілості за CRC. `foreign: true` — docPath існує, але БЕЗ `docgen:`-CRC у frontmatter: рукописна (людська) дока. Така дока вважається чинною документацією файлу (`stale: false`) — генерація її мовчки не перезаписує (перезапис лише explicit `--overwrite`, який бере всі цілі без фільтра). Живий кейс: `npm/docs/index.md` — людський зміст модуля у проєкті-споживачі; сканер бачив його як `missing` і затирав чат-філером моделі. - scanOrphanedDocs — Знаходить "сирітські" доки: `docs/.md` із `resource:` + `docgen.crc` у frontmatter, у яких відповідний source-файл (resource:) вже не існує. Перевіряє лише файли, згенеровані `fix-doc-files` (наявність `docgen.crc` у frontmatter). Directory Index (resource із `/` на кінці) та ручні доки без `resource:` або без CRC — ігноруються. - scanForDocFiles — Рекурсивно обходить дерево від `root`, повертає кодові файли зі станом застарілості. Синхронний `readdirSync` — детермінований порядок без гонок; обсяг дерева це дозволяє. Поверх `DOCGEN_IGNORE_GLOBS` відсіює ще й те, що в `.gitignore` (через git check-ignore). - resolveRoot — Парсить `--root ` з argv; default — cwd. ## Сценарії використання - `npm/rules/doc-files/docgen-scan/tests/docgen-scan.test.mjs` (isSourceFile; docPathForSource) — js/mjs/ts/vue — з декларації @7n/rules-lang-js, не вбудовані (фаза 5b); .py/.rs — з активними lang-плагінами (декларація в маніфесті); без активного lang-плагіна розширення не документується; пропускає .d.ts, тести й некодові розширення; кладе docs/.md поряд із джерелом; ще 13 ## Гарантії поведінки - Власних операцій запису (ФС/БД) у файлі немає; виклики імпортованих модулів можуть писати. - Містить локальні fail-safe гілки; інші помилки можуть поширюватися назовні.