doctrace

Overview • Features • Motivation • Quick Start • Commands • Configuration • Contributing • License

🎺 Overview

Keep documentation in sync with code. When files change, know exactly which docs need review - and in what order.

  src/booking/handler.ts changed
               │
               v
      ┌───────────────────┐
      │ doctrace affected │
      └────────┬──────────┘
               │
               v
  ┌─────────────────────────────────┐
  │ Direct hits:                    │
  │   docs/bookings.md              │  ← has "sources: src/booking/"
  │                                 │
  │ Indirect hits:                  │
  │   docs/payments.md              │  ← requires docs/bookings.md
  └─────────────────────────────────┘

Preview

---
required_docs:
  - docs/payments.md: payment integration

sources:
  - src/booking/: booking module
  - src/booking/commands/: command handlers
---

# Booking System

How bookings work...

doctrace affected docs/ --last 1

Direct hits (1):
  docs/bookings.md       <- references src/booking/

Indirect hits (1):
  docs/payments.md       <- referenced BY docs/bookings.md

⭐ Features

• Impact analysis: detects which docs need review when code changes, with cascading through dependencies
• AI-ready output: JSON output feeds AI agents to auto-update docs based on code changes
• Interactive UI: browser dashboard to explore and visualize doc dependencies
• Auto-gen index: generates index.md table from frontmatter metadata

❓ Motivation

In large codebases, docs get outdated because:

1. No one remembers which docs need updating when a file changes
2. AI agents don't know which files to read to understand each doc

doctrace solves this by adding "hints" to each doc - sources: tells any AI exactly what to read.

🚀 Quick Start

Install:

brew install pipx         # if not installed (macOS/linux)
pipx install doctrace     # or: pip install doctrace

Add metadata to your docs:

---
required_docs:
  - docs/other-feature.md: hard dependency

related_docs:
  - docs/related.md: soft reference

sources:
  - src/feature/: main module
  - src/feature/utils.ts: helper functions
---

# My Feature

Documentation content here...

Setup in your repo:

cd your-repo
doctrace init                        # creates doctrace.json (optional)

doctrace info docs/                  # show phases + validate refs
doctrace affected docs/ --last 5     # find docs affected by last 5 commits
doctrace preview docs/               # interactive explorer in browser

📖 Commands

doctrace info <path>                           # show phases + validate refs
doctrace affected <path> --last <N>            # list affected docs by last N commits
doctrace affected <path> --since <ref>         # list affected docs since ref (commit/tag/branch)
doctrace affected <path> --base-branch <branch># list affected docs from merge-base
doctrace affected <path> --json                # output as JSON
doctrace preview <path>                        # interactive explorer in browser
doctrace preview <path> --port <N>             # preview on custom port (default 8420)
doctrace init                                  # create doctrace.json
doctrace index <path> -o <file>                # generate index.md from frontmatter
doctrace completion <shell>                    # generate shell completion script
doctrace --version                             # show version

Direct hits (3):
  docs/concepts.md
  docs/api.md
  docs/utils.md

Indirect hits (1):
  docs/overview.md <- docs/api.md

Phases (3):
  1. docs/concepts.md, docs/utils.md
  2. docs/api.md
  3. docs/overview.md

⚙️ Configuration

{
  "metadata": {
    "required_docs_key": "required_docs",
    "related_docs_key": "related_docs",
    "sources_key": "sources"
  }
}

# zsh - add to ~/.zshrc
eval "$(doctrace completion zsh)"

# bash - add to ~/.bashrc
eval "$(doctrace completion bash)"

# fish
doctrace completion fish | source

🤝 Contributing

make install    # venv + deps + pre-commit
make test       # run tests
make format     # ruff fix + format
make check      # validate ruff rules
make build      # build package
make clean      # remove venv + dist

Dev alias:

ln -sf $(pwd)/.venv/bin/doctrace ~/.local/bin/doctraced   # install
rm ~/.local/bin/doctraced                                 # remove

📜 License

This project is licensed under the MIT License.