Introducing Treedocs: Automated Documentation Staleness Detection

Treedocs is a Swift-based CLI tool (v0.2.0) designed for macOS 13+ that helps developers grasp any codebase more efficiently by maintaining a documented map of every directory and file.

🌳 Visualizing the Repository

By simply executing treedocs, you get an immediate bird's-eye view of your project. The tool uses color-coding to highlight the health of your documentation:

• Green: Current, valid files.
• Red: Stale or invalid entries that require attention.

Example Output

├── README.md           User-facing overview, installation, and command usage documentation.
├── Sources/            Swift package source code for the treedocs executable.
│   ├── Commands/       ArgumentParser command implementations for treedocs subcommands.
│   └── Core/           Core services for loading, scanning, rendering, and updating treedocs data.
├── site/               Static files deployed to the project GitHub Pages site.
│   ├── index.html      Landing page for the treedocs GitHub Pages site.
│   └── styles.css      Stylesheet for the treedocs GitHub Pages landing page.
└── old-file.swift      STALE: no matching path exists on disk.

---

🚀 Why Use Treedocs?

"Documentation is only useful if it is accurate. Treedocs ensures your project map evolves alongside your code."

1. Accelerated Onboarding: Provide new hires, your future self, or AI coding agents with the precise context needed to navigate complex folders. Stop wandering aimlessly through directories.
2. Drift Prevention: Use automatic checks to ensure documentation doesn't rot. You can integrate a Git pre-commit hook to block any undocumented changes from being committed.
3. Contextual Reviews: By storing human-readable summaries in a version-controlled treedocs.yaml, PR reviews become simpler and AI agents consume fewer tokens because they don't have to rediscover the project structure.

The Staleness Logic

The tool essentially evaluates the state of a file entry using a simple logical check: $\text{Status} = \begin{cases} \text{Valid} & \text{if } \text{Path}_{\text{yaml}} \in \text{Disk} \\ \text{Stale} & \text{if } \text{Path}_{\text{yaml}} \notin \text{Disk} \end{cases}$

---

🛠 Installation & Setup

Note: Version 0.2.0 is currently source-build only. You will need a Swift 6-compatible environment (typically Xcode 16+).

Method	Command	Note
mise	MISE_EXPERIMENTAL=true mise use -g spm:DandyLyons/treedocs@0.2.0	Uses experimental SPM backend; builds from source.
Homebrew	brew install DandyLyons/tap/treedocs	Builds from source via the DandyLyons tap.
Mint	mint install DandyLyons/treedocs@0.2.0	Builds the executable from the tagged GitHub source.

Quick Start Checklist

• Initialize the project: treedocs init (Creates treedocs.yaml)
• Sync the structure: treedocs sync (Updates paths and checks for errors)
• Verify integrity: treedocs check (Validates the YAML file)
• View the tree: treedocs

---

📋 The treedocs.yaml Schema

The heart of the tool is the treedocs.yaml file. This is a version-controlled map that mirrors your file tree, pairing every path with a human-readable description.

Key Technical Details:

• Standardization: The format follows a canonical JSON Schema.
• Interoperability: Because it uses a schema, treedocs is easily understood by CI/CD pipelines, IDEs, and AI agents.
• Automation: You can use AI agents to populate the descriptions, then verify them using treedocs check.

Workflow Diagram

To run a help command via Mint, use: mint run DandyLyons/treedocs@0.2.0 --help