doksnet 1.1.2

A CLI tool for documentation-code mapping verification using cryptographic hashes
doksnet-1.1.2 is not a library.

🦀 doksnet

CI Quick Check Crates.io Documentation

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

From crates.io (Recommended)

# Install from crates.io
cargo install doksnet

From GitHub Releases

Download pre-built binaries from GitHub Releases:

  • Linux: doksnet-linux-amd64
  • Windows: doksnet-windows-amd64.exe
  • macOS: doksnet-macos-amd64 (Intel) or doksnet-macos-arm64 (Apple Silicon)

From Source (Development)

# Clone and build from source
git clone https://github.com/Pulko/doksnet
cd doksnet
cargo install --path .

📋 Commands Overview

Command Purpose Interactive CI/CD Safe
new Initialize a .doks file ✅ ❌
add Create doc↔code mappings ✅ ❌
edit <id> Edit specific mapping ✅ ❌
remove-failed Remove all failed mappings ✅ ❌
test Verify all mappings ❌ ✅
test-interactive Test with guided fixing ✅ ❌

🛠 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

The .doks file uses a compact, machine-optimized format:

# .doks v2 - Compact format
version=0.2.0
default_doc=README.md

# Format: id|doc_partition|code_partition|doc_hash|code_hash|description
a1b2c3d4|README.md:10-15|src/lib.rs:20-35|abc123def456...|789xyz012abc...|API usage example
main-func|README.md:25-30|src/main.rs:1-10|fedcba987654...|123456789abc...|Main function example

Benefits of the compact format:

  • 📦 5x smaller than TOML (faster parsing, less storage)
  • ⚡ Machine-optimized (perfect for automation)
  • 🔧 Grep-friendly (easy to analyze with standard tools)
  • 🚀 Simple parsing (no complex dependencies)

🔄 Typical Workflow

Local Development

# 1. Initialize project
doksnet new

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

# 3. Test locally
doksnet test

# 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

CI/CD Integration

Using GitHub Action (Recommended):

# .github/workflows/docs.yml
name: Documentation Sync

on: [push, pull_request]

jobs:
  verify-docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: Pulko/doksnet@v1

Manual Installation:

# In your CI/CD pipeline
cargo install doksnet
doksnet test  # Fails build if docs/code drift apart

🎯 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

🚀 GitHub Action

Doksnet provides a ready-to-use GitHub Action for seamless CI/CD integration:

Basic Usage

name: Documentation Sync Check
on: [push, pull_request]

jobs:
  verify-docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: Pulko/doksnet@v1
        # Uses defaults: command='test', fail-on-error=true

Advanced Configuration

- uses: Pulko/doksnet@v1
  with:
    command: 'test'           # Command to run
    version: 'latest'         # Doksnet version  
    working-directory: '.'    # Directory to run in
    fail-on-error: true       # Fail workflow on issues

Action Inputs

Input Description Default Options
command Doksnet command to run test test, remove-failed
version Doksnet version to use latest latest, 0.2.0, etc.
working-directory Directory to run doksnet in . Any valid path
fail-on-error Fail workflow if issues found true true, false

Action Outputs

Output Description
result Full output from doksnet command
exit-code Exit code (0 = success, 1 = failure)

Common Patterns

Enforce Documentation Sync (Fail Build):

- uses: Pulko/doksnet@v1
  # Fails CI if docs are out of sync (default behavior)

Warning Only (Don't Fail Build):

- uses: Pulko/doksnet@v1
  with:
    fail-on-error: false

Cleanup Failed Mappings:

- uses: Pulko/doksnet@v1
  with:
    command: 'remove-failed'

Benefits:

  • ✅ Zero setup - No need to install Rust/Cargo
  • ⚡ Fast - Cached dependencies, optimized for CI
  • 🔧 Flexible - Configurable commands and error handling
  • 🌍 Cross-platform - Works on Linux, Windows, macOS

🚧 Future Extensions

  • 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