doctrace 0.2.3

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
              │
              v
  ┌───────────────────────────────────┐
  │ doctrace affected docs/ --last 1  │
  └───────────────────────────────────┘
              │
              v
  ┌───────────────────────────────────┐
  │ Direct hits:                      │
  │   docs/bookings.md                │  ← has "sources: src/booking/"
  │                                   │
  │ Indirect hits:                    │
  │   docs/payments.md                │  ← referenced BY docs/bookings.md
  └───────────────────────────────────┘

How it works

Each doc has YAML frontmatter with metadata sections:

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

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

# Booking System

How bookings work...

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

• info - shows doc phases and validates refs
• affected - finds docs affected by code changes (with dependency ordering)
• preview - interactive docs explorer in browser
• base - manages base commit for incremental analysis
• index - generates index.md from frontmatter metadata
• completion - generates shell completion scripts (zsh/bash/fish)

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.

Quickstart

1. Install

pipx install doctrace

2. Add metadata to your docs

Add YAML frontmatter at the top of 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...

3. Initialize config (optional)

doctrace init    # creates doctrace.json

Config options

doctrace.json (at repo root):

{
  "metadata": {
    "required_docs_key": "required_docs",
    "related_docs_key": "related_docs",
    "sources_key": "sources"
  },
  "base": {
    "commit_hash": "abc123...",
    "commit_message": "feat: something",
    "commit_date": "2026-02-17T10:30:00+00:00",
    "analyzed_at": "2026-02-17T20:55:32+00:00"
  }
}

options:

• metadata.required_docs_key: frontmatter key for required docs (default: "required_docs")
• metadata.related_docs_key: frontmatter key for related docs (default: "related_docs")
• metadata.sources_key: frontmatter key for source refs (default: "sources")
• base: set by doctrace base update

4. Use it

doctrace info docs/                         # show phases + validate refs
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 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
doctrace affected <path> --since-base	list affected docs since base 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 base update	save current commit as base
doctrace base show	show base state
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

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 info docs/    # practical test

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