doctrace 0.2.0

Track doc dependencies and detect affected docs from code changes

Overview

CLI tool that keeps documentation in sync with code in large codebases. Detects which docs are affected by code changes.

  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