🦀 doksnet

A Rust CLI tool for documentation ↔ code mapping verification. Create lightweight symbolic links between documentation sections and code snippets, then verify that both sides stay synchronized using cryptographic hashes.

🚀 Installation

# Clone and build
git clone <repository>
cd doksnet
cargo build --release

# Install globally (optional)
cargo install --path .

📋 Commands Overview

🛠 Usage Guide

1. Initialize Project

# Create .doks file in current directory
doksnet new

# Create .doks file in specific directory  
doksnet new /path/to/project

What it does:

• Scans for documentation files (README.md, etc.)
• Prompts you to select default documentation file
• Creates .doks configuration file

2. Create Documentation-Code Mappings

doksnet add

Interactive flow:

1. Documentation partition: README.md:15-25 or README.md:10-20@5-30
2. Content preview: Shows extracted documentation text
3. Confirmation: Verify the selection is correct
4. Code partition: src/lib.rs:45-60 or src/main.rs:10-25@10-50
5. Content preview: Shows extracted code text
6. Confirmation: Verify the selection is correct
7. Description: Optional description for the mapping
8. Hash generation: Creates Blake3 hashes and saves mapping

3. Edit Existing Mappings

# Edit by ID (first 8 characters sufficient)
doksnet edit a1b2c3d4

What you can edit:

• Documentation partition reference
• Code partition reference
• Description
• Both partitions at once

Features:

• Shows current values
• Pre-fills input with existing values
• Previews new content before applying
• Updates hashes automatically

4. Test Mappings (CI/CD)

# Non-interactive testing for automation
doksnet test

Output:

• ✅ PASS: Content matches stored hashes
• ❌ FAIL: Content has changed
• Exit code 1 if any mappings fail (perfect for CI/CD)

5. Interactive Testing & Fixing

# Interactive mode with change preview
doksnet test-interactive

For each failed mapping, you can:

• Update hashes: Accept current content as new baseline
• Edit mapping: Redirect to doksnet edit <id>
• Remove mapping: Delete the broken mapping
• Skip: Leave as-is for now

Shows:

• Current content that changed
• Hash mismatches
• Detailed change previews

6. Bulk Remove Failed Mappings

# Remove all mappings that fail verification
doksnet remove-failed

Safety features:

• Lists all failed mappings before removal
• Shows failure reasons (doc/code/both)
• Requires confirmation before deletion

📄 Partition Format

Partitions use this lightweight format to reference file ranges:

<relative_path>:<start_line>-<end_line>@<start_col>-<end_col>

Examples:

• README.md - Entire file
• README.md:10-20 - Lines 10-20
• README.md:15 - Single line 15
• src/lib.rs:10-20@5-30 - Lines 10-20, columns 5-30
• docs/guide.md:1-5@1-50 - First 5 lines, first 50 characters

Notes:

• Line numbers are 1-indexed
• Column numbers are 1-indexed
• Ranges are inclusive
• Non-contiguous ranges require multiple mappings

🔐 Hash-Based Verification

How it works:

1. Text → Hash: Extract content from partition → Generate Blake3 hash
2. Hash ← Text: Re-extract content → Compare with stored hash
3. Change Detection: Any character-level change produces different hash

What's detected:

• Content changes
• Whitespace modifications
• Line ending changes
• File deletions/moves
• Invalid partition ranges

📁 .doks File Structure

version = "0.1.0"
default_doc = "README.md"

[[mappings]]
id = "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
doc_partition = "README.md:10-15"
code_partition = "src/lib.rs:20-35"
doc_hash = "abc123def456..."
code_hash = "789xyz012abc..."
description = "API usage example"

🔄 Typical Workflow

# 1. Initialize project
doksnet new

# 2. Create mappings between docs and code
doksnet add   # Repeat as needed

# 3. In CI/CD pipeline
doksnet test  # Fails build if docs/code drift apart

# 4. When changes are detected
doksnet test-interactive  # Guided fixing

# 5. Edit specific mappings
doksnet edit a1b2c3d4

# 6. Clean up broken mappings
doksnet remove-failed

🎯 Use Cases

• API Documentation: Link examples in README to actual implementation
• Tutorial Sync: Ensure code samples in guides match working code
• Architecture Docs: Connect design decisions to code structures
• Code Reviews: Verify documentation updates accompany code changes
• Legacy Code: Track which docs describe which code sections

🚧 Future Extensions

• CI/CD Integration: Pre-built GitHub Actions
• VSCode Extension: GUI for creating/managing mappings
• Diff Visualization: Show exact changes between versions
• Batch Operations: Mass edit/update operations
• Export Formats: Generate reports in various formats

Built with ❤️ in Rust • Lightweight • Fast • Reliable