https://github.com/delorenj/syntropy
Fighting documentation heat death through algorithmic governance. Python CLI tool for maintaining documentation integrity with Hub-and-Spoke topology validation and session-based staleness tracking.
https://github.com/delorenj/syntropy
cli developer-tools documentation documentation-tools entropy governance knowledge-management markdown pydantic python
Last synced: 2 months ago
JSON representation
Fighting documentation heat death through algorithmic governance. Python CLI tool for maintaining documentation integrity with Hub-and-Spoke topology validation and session-based staleness tracking.
- Host: GitHub
- URL: https://github.com/delorenj/syntropy
- Owner: delorenj
- Created: 2025-12-22T11:30:40.000Z (6 months ago)
- Default Branch: main
- Last Pushed: 2025-12-22T11:36:28.000Z (6 months ago)
- Last Synced: 2025-12-23T22:45:06.741Z (6 months ago)
- Topics: cli, developer-tools, documentation, documentation-tools, entropy, governance, knowledge-management, markdown, pydantic, python
- Language: Python
- Size: 302 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Syntropy
Fighting documentation heat death through algorithmic governance
A Python CLI tool that maintains documentation integrity by enforcing structure and tracking staleness. Implements Hub-and-Spoke topology validation with session-based decay detection to prevent documentation entropy.
## Features
- **Hub-and-Spoke Topology**: Enforce navigable documentation structure (Root documents link to Leaf documents)
- **Staleness Detection**: Track documentation age based on coding sessions, not just time
- **Graceful Degradation**: Malformed YAML frontmatter never crashes, creates "corrupted" state
- **Performance-First**: <3 second SLA with aggressive caching and incremental parsing
- **Type-Safe**: Full Pydantic validation with clear error messages
- **Rich CLI**: Beautiful terminal output with colors, tables, and progress indicators
- **Dual Configuration**: YAML frontmatter in docs (metadata) + TOML config file (tool settings)
## Installation
### Prerequisites
- Python 3.12 or higher
- [uv](https://github.com/astral-sh/uv) package manager
### Install with uv
```bash
cd syntropy
uv sync
```
This will:
1. Create a virtual environment
2. Install all dependencies
3. Install syntropy in editable mode
### Verify Installation
```bash
uv run syntropy --version
# Output: syntropy, version 0.1.0
uv run syntropy --help
# Output: Documentation Entropy Control System usage
```
## Quick Start
### 1. Create Configuration
The tool uses **TOML format for configuration** (not YAML):
```bash
# Option 1: Copy the example config file
cp .syntropy.toml.example .syntropy.toml
# Option 2: Generate default config programmatically
uv run python -c "from syntropy.config import create_default_config; from pathlib import Path; create_default_config(Path('.syntropy.toml'))"
```
Edit `.syntropy.toml` (TOML format) to customize:
```toml
doc_root = "docs/"
graph_depth_limit = 2
staleness_threshold = 3
[domain_mapping]
authentication = ["app/oauth_*.py", "extension/src/auth/**"]
backend_api = ["app/routes.py", "app/utils.py"]
# ... more domains
```
### 2. Add YAML Frontmatter to Docs
Documentation files use **YAML frontmatter for metadata** (this is separate from the TOML config file).
Root document (e.g., `docs/Map.md`):
```markdown
---
type: root
parent: null
last_verified_session: 1
domain: meta
tags: ["navigation", "index"]
---
# Documentation Map
## Authentication
See [Authentication Flows](./auth-flow.md)
```
Leaf document (e.g., `docs/auth-flow.md`):
```markdown
---
type: leaf
parent: "docs/Map.md"
last_verified_session: 1
domain: authentication
tags: ["oauth", "jwt"]
---
# Authentication Flows
Details about OAuth implementation...
```
### 3. Run Entropy Check
```bash
# Full check: parse → audit → report
uv run syntropy check
# Individual commands
uv run syntropy parse # Build graph
uv run syntropy audit # Validate topology
uv run syntropy report # Display results
```
## Usage
### Commands
#### `syntropy check`
Run full entropy check (parse → audit → report). This is the primary command.
```bash
uv run syntropy check
uv run syntropy check --force # Ignore cache
uv run syntropy check --session 10 # Specify session number
uv run syntropy check --format json # JSON output
```
#### `syntropy parse`
Build/cache documentation graph from filesystem.
```bash
uv run syntropy parse
uv run syntropy parse --force # Force full reparse
```
#### `syntropy audit`
Run topology validation and staleness detection.
```bash
uv run syntropy audit
uv run syntropy audit --session 15 # Specify session number
```
#### `syntropy report`
Generate and display entropy report.
```bash
uv run syntropy report
uv run syntropy report --format markdown
uv run syntropy report --format json --output report.json
```
### Configuration
#### Understanding Configuration Formats
This tool uses **two different formats** for different purposes:
1. **TOML** (`.syntropy.toml`): Tool configuration file
- Controls how the tool operates
- Settings like doc_root, graph_depth_limit, staleness_threshold
- Uses TOML syntax: `key = "value"`, `[sections]`, etc.
2. **YAML** (frontmatter in `.md` files): Documentation metadata
- Metadata for individual documentation files
- Information like type, parent, last_verified_session
- Uses YAML syntax within `---` delimiters in markdown files
**Why two formats?**
- YAML frontmatter is the standard for markdown metadata
- TOML is more Pythonic and better for tool configuration
- Each format is optimized for its purpose
#### Configuration File (TOML)
Place `.syntropy.toml` (TOML format) in your project root:
```toml
doc_root = "docs/" # Documentation directory
graph_depth_limit = 2 # Max hops from root to leaf
staleness_threshold = 3 # Sessions before marked stale
cache_file = ".docs_cache.json" # Cache location
excluded_patterns = ["node_modules/", "venv/"]
[domain_mapping]
# Map code patterns to documentation domains
authentication = ["app/oauth_*.py", "extension/src/auth/**"]
```
#### Environment Variables
Override config with environment variables:
```bash
export DOC_ENTROPY_DOC_ROOT="documentation/"
export DOC_ENTROPY_GRAPH_DEPTH_LIMIT=3
export DOC_ENTROPY_STALENESS_THRESHOLD=5
export DOC_ENTROPY_CACHE_FILE=".cache.json"
uv run syntropy check
```
### Custom Config File
```bash
uv run syntropy --config custom.toml check
```
### Verbose Output
```bash
uv run syntropy --verbose check
```
## YAML Frontmatter Schema
### Root Document
```yaml
---
type: root # Must be "root"
parent: null # Must be null
last_verified_session: 12 # Session number (>= 1)
domain: "meta" # Domain name
tags: ["navigation"] # Optional tags
---
```
### Leaf Document
```yaml
---
type: leaf # Must be "leaf"
parent: "docs/Map.md" # Required: path to parent root
last_verified_session: 12 # Session number (>= 1)
domain: "authentication" # Domain name
tags: ["oauth", "jwt"] # Optional tags
dependencies: [] # Optional dependencies
---
```
## Development Status
**Current Phase**: Sprint 1-1 (Foundation) ✅
**Implemented**:
- ✅ Project structure and packaging
- ✅ Core Pydantic data models
- ✅ TOML configuration system
- ✅ Click-based CLI with Rich output
- ✅ Comprehensive unit tests (90%+ coverage)
**Coming Next** (Sprint 1-2):
- 📅 File scanner with .gitignore support
- 📅 YAML frontmatter parser with graceful degradation
- 📅 mtime-based cache manager
- 📅 NetworkX graph builder
**Future Phases**:
- Sprint 1-3: Topology validation and staleness detection
- Sprint 1-4: Rich terminal reporting and mise integration
- MVP-2: Migration tooling and export formats
See [DEVELOPMENT.md](./DEVELOPMENT.md) for contributor guide.
## Architecture
### Hub-and-Spoke Topology
```
Map.md (Root)
├── Architecture.md (Root)
│ ├── backend-design.md (Leaf)
│ └── data-models.md (Leaf)
└── API.md (Root)
├── endpoints.md (Leaf)
└── authentication.md (Leaf)
```
**Constraints**:
- Max depth: 2 hops (Root → Intermediate → Leaf)
- Each leaf has exactly one parent
- No circular references (DAG structure)
- All docs reachable from Map.md
### Performance
**SLA: <3 seconds** for complete check on 500 documents
Breakdown (typical):
- Parse: 0.5s (warm cache) / 2.5s (cold)
- Audit: <100ms
- Report: <500ms
**Optimization strategies**:
- mtime-based caching
- Incremental graph updates
- O(n) algorithms for topology validation
## Troubleshooting
### Error: "Config file already exists"
```bash
# Remove existing config first
rm .syntropy.toml
# Then regenerate
uv run python -c "from syntropy.config import create_default_config; from pathlib import Path; create_default_config(Path('.syntropy.toml'))"
```
### Error: "Leaf documents must specify a parent"
Your document has `type: leaf` but `parent: null`. Either:
1. Change `type: root` (if it's a hub document)
2. Add `parent: "docs/ParentDoc.md"`
### Error: "Root documents must not have a parent"
Your document has `type: root` but also specifies a parent. Change `parent: null`.
### Warning: "File path must be absolute"
Document model requires absolute paths. This is typically handled internally but may appear in error messages.
## License
MIT License - See LICENSE file for details
## Contributing
See [DEVELOPMENT.md](./DEVELOPMENT.md) for:
- Development setup
- Running tests
- Code style guidelines
- Architecture documentation
## Support
For issues, questions, or contributions:
- GitHub Issues: (coming soon)
- Email: dev@intelliforia.com