ascfix

Automatic ASCII diagram repair tool for Markdown files.

Overview

ascfix fixes misaligned ASCII diagrams in Markdown, especially those generated by LLMs. It normalizes box widths, aligns arrows, enforces uniform padding, and ensures diagrams remain maintainable.

Ideal for:

AI-generated documentation with ASCII diagrams
Markdown files with workflow diagrams
CI/CD pipeline documentation
Architecture diagrams in code repositories

Features

Safe mode: Normalize Markdown tables (default)
Diagram mode: Repair ASCII boxes and arrows
Check mode: Validate files without modifying (exit codes for CI/CD)
Conservative: Only fixes well-understood structures
Idempotent: Running twice produces identical output
Fast: Linear processing time
Safe: No panics on untrusted input

Installation

From crates.io

cargo install ascfix

From source

git clone https://github.com/evoludigit/ascfix.git
cd ascfix
cargo install --path .

Usage

# Check a file (default: safe mode, output to stdout)
ascfix README.md

# Fix a file in place (default: safe mode)
ascfix README.md --in-place

# Enable diagram mode for box/arrow repair
ascfix README.md --in-place --mode=diagram

# Validate without modifying (check mode)
ascfix README.md --check --mode=diagram
# Returns exit code 1 if changes would be made

# Process multiple files
ascfix docs/*.md --in-place --mode=diagram

Modes

Mode	Description	Use Case
`safe`	Fix only Markdown tables	Conservative, safe for any file
`diagram`	Fix boxes and arrows	For files with ASCII diagrams
`check`	Validate without writing	CI/CD validation

Building & Testing

# Run all tests
cargo test

# Check code quality
cargo clippy --all-targets --all-features -- -D warnings

# Build release binary
cargo build --release

All code is tested with TDD discipline - unit tests, integration tests, and golden file tests.

License

Licensed under the MIT License (LICENSE or https://opensource.org/licenses/MIT)

Contribution

Contributions are welcome! Please feel free to submit pull requests.

ascfix 0.1.0