ascii-guard

What it is and what it does

ascii-guard is a linter and auto-fixer for ASCII art boxes commonly found in documentation. It detects misalignments where box borders (drawn with Unicode box-drawing characters like ─, │, ┌, ┐, └, ┘) are off by 1–2 characters, which is a frequent artifact in AI-generated diagrams. The tool validates vertical alignment of │ characters, horizontal alignment of ─ characters, corner correctness, width consistency across top/middle/bottom borders, and content fit within boxes.

It runs as both a CLI tool (lint and fix modes, with dry-run preview) and a Python library with functions like lint_file(), fix_file(), detect_boxes(), and validate_box(). The package has minimal dependencies—zero for Python 3.11+, one (tomli) for Python 3.10—and is built on the standard library, making it lightweight and fast to install and run.

Use it for:

• Validate ASCII flowcharts and diagrams in markdown documentation before publishing to catch subtle alignment errors introduced by AI tools
• Auto-fix misaligned boxes in bulk across a documentation directory using the CLI or Python API in a CI/CD pipeline
• Integrate into a documentation build process to enforce consistent ASCII art formatting without manual review
• Show intentionally broken boxes in tutorials or before/after examples using ignore markers to skip validation on specific blocks
• Detect and report all ASCII boxes in a file programmatically for custom processing or metrics collection

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Detects and fixes misaligned ASCII art boxes in documentation by validating box-drawing character alignment and automatically correcting width, corner, and border inconsistencies.

Yes. The package solves a real problem (AI-generated ASCII art misalignment) with minimal supply-chain risk, zero dependencies on modern Python, active maintenance, and a stable API. No known vulnerabilities. Install if you maintain documentation with ASCII diagrams or generate them programmatically.

Install

ascii-guard on PyPI

pip install ascii-guard

uv add ascii-guard

poetry add ascii-guard

Installing ascii-guard

Before you install

Low friction: pure wheel install with one optional runtime dependency (tomli) only for Python 3.10; Python 3.11+ requires no external dependencies. Active maintenance with recent commits and stable production status.

License in practice

Apache-2.0 permissive license allows use in commercial and open-source projects with minimal restrictions; attribution required but no copyleft obligations.

Quickstart

# Install
pip install ascii-guard

# CLI: lint a file
ascii-guard lint README.md

# CLI: auto-fix with preview
ascii-guard fix --dry-run README.md

# Python API
from ascii_guard import lint_file
result = lint_file("README.md")
if result.has_errors:
    for error in result.errors:
        print(f"Line {error.line + 1}: {error.message}")

Requires Python 3.10 or later; Python 3.10 requires tomli as a runtime dependency (automatically installed).

Verify before relying

• Whether the package handles all edge cases in nested or overlapping ASCII box structures beyond the documented flowchart examples
• Performance characteristics on large documentation files with hundreds of boxes

Package facts

Evidence: ascii_guard-2.3.0-py3-none-any.whl

Keywords: ascii, linter, documentation, ascii-art, box-drawing

Tags

More Text Processing packages