---
docgen:
  source: npm/scripts/dispatcher/trace.mjs
  crc: 8d541669
  score: 100
---

# trace.mjs

## Огляд

Файл забезпечує наскрізну простежуваність артефактів. Він читає front-matter з директорій `docs/{tasks,specs,plans,adr}`, будує ланцюг за лінками та позначає розриви. Функції генерують аналіз, який потім рендериться у текстовий вивід, а трасування виконується для зчитування артефактів.

## Поведінка

parseFrontMatter Парсить плаский YAML-front-matter. Не обробляє вкладеність. Відрізає інлайн-коментарі.

analyze Будує аналіз. Для кожного артефакту генерує лінки з позначкою про розрив.

render Текстовий рендер аналізу. Форматує вивід для читання.

runTraceCli Виконує трасування. Зчитує артефакти з директорій. Будує аналіз. Повертає код виходу.

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

parseFrontMatter — Парсить плаский YAML-front-matter (key: value). Обробляє лише основні поля spec/plan/task-record. Видаляє інлайн-коментарі.
analyze — Створює аналіз: для кожного артефакту — зв'язок його лінків зі статусом ok/розрив. `breaking` означає відсутність лінка, що руйнує ланцюг.
render — Відображає текстовий вивід аналізу.
runTraceCli — Виконує команду CLI `n-cursor trace [--json]`. Повертає 1, якщо виявлено розриви ланцюга.

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

- Read-only: файл не виконує операцій запису у файлову систему.
- За невдачі повертає значення помилки (`false`/`null`/`Err`) замість генерування винятку чи паніки.
- Не звертається до мережі.
