doctrace 0.2.1

Track doc dependencies and detect affected docs from code changes

doctrace

Trace documentation dependencies in large codebases. When code changes, know exactly which docs need review - and in what order.

Add metadata hints to your docs, and doctrace builds a dependency graph that maps code→docs and docs→docs relationships. AI agents use these hints to know exactly what to read when validating or updating documentation.

  src/booking/handler.ts changed
              │
              ▼
  ┌───────────────────────────────────┐
  │ doctrace affected docs/ --last 1   │
  └───────────────────────────────────┘
              │
              ▼
  ┌───────────────────────────────────┐
  │ Direct hits:                      │
  │   docs/bookings.md                │  ← has "related sources: src/booking/"
  │                                   │
  │ Indirect hits:                    │
  │   docs/payments.md                │  ← referenced BY docs/bookings.md
  └───────────────────────────────────┘

How it works

Each doc ends with metadata sections:

# Booking System

How bookings work...

---

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

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

When src/booking/handler.ts changes:

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

The propagation: if bookings.md might be outdated, then payments.md (which references it) might also need review.

Interactive preview explorer

Interactive panel to visualize dependencies between docs, edit content, and explore git history.

Features

• validate - validates all referenced paths exist
• affected - finds docs affected by code changes (with dependency ordering)
• preview - interactive docs explorer in browser
• lock - manages lock state for incremental analysis

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 validate each doc

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

Quickstart

1. Install

pipx install doctrace

2. Add metadata to your docs

Custom style (default) - metadata at bottom

# My Feature

Documentation content here...

---

related docs:
- docs/other-feature.md - brief description

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

Frontmatter style - metadata at top

---
related docs:
  - docs/other-feature.md - brief description

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

# My Feature

Documentation content here...

Config required:

{
  "metadata": {
    "style": "frontmatter"
  }
}

3. Initialize config (optional)

doctrace init    # creates .doctrace/ folder

Config options

.doctrace/
├── config.json   # required
├── lock.json     # tracks last analyzed commit
└── syncs/        # output directory (added to .gitignore)

config.json:

{
  "ignored_paths": ["**/migrations/**", "**/*.test.ts"],
  "affected_depth_limit": null,
  "metadata": {
    "style": "custom",
    "docs_key": "related docs",
    "sources_key": "related sources",
    "require_separator": true
  }
}

metadata options:

• style: "frontmatter" (YAML at top) or "custom" (flexible format)
• docs_key: header for doc references (default: "related docs")
• sources_key: header for source references (default: "related sources")
• require_separator: if true, only parse after --- (default: true, custom only)

4. Use it

doctrace validate docs/                     # validate all refs exist
doctrace affected docs/ --last 5            # find docs affected by last 5 commits
doctrace affected docs/ --since v1.0.0      # find docs affected since tag/commit/branch
doctrace preview docs/                      # interactive explorer in browser

All commands

Command	Description
doctrace validate <path>	validate refs exist
doctrace affected <path> --last <N>	list affected docs by last N commits
doctrace affected <path> --since <ref>	list affected docs since ref
doctrace affected <path> --since-lock	list affected docs since lock commit
doctrace affected <path> --base-branch <branch>	list affected docs from merge-base
doctrace affected <path> --verbose	show changed files and match details
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 lock update	save current commit to lock.json
doctrace lock show	show lock.json state
doctrace init	create .doctrace/ folder
doctrace --version	show version

Example output

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

Phases show dependency order - useful for AI agents processing docs.

Development

make install           # create venv + install
make check             # lint
make test              # run tests
doctrace validate docs/ # practical test

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