https://github.com/fxstein/ascii-guard
Zero-dependency Python linter for detecting and fixing misaligned AI ASCII art boxes in documentation
https://github.com/fxstein/ascii-guard
agent ai cursor python
Last synced: 4 months ago
JSON representation
Zero-dependency Python linter for detecting and fixing misaligned AI ASCII art boxes in documentation
- Host: GitHub
- URL: https://github.com/fxstein/ascii-guard
- Owner: fxstein
- License: apache-2.0
- Created: 2025-11-16T10:54:31.000Z (8 months ago)
- Default Branch: main
- Last Pushed: 2026-03-02T21:54:11.000Z (4 months ago)
- Last Synced: 2026-03-03T00:38:16.836Z (4 months ago)
- Topics: agent, ai, cursor, python
- Language: Python
- Homepage:
- Size: 1.11 MB
- Stars: 17
- Watchers: 1
- Forks: 0
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# ascii-guard
**Zero-dependency Python linter for detecting and fixing misaligned ASCII art boxes in documentation.**
[](https://opensource.org/licenses/Apache-2.0)
[](https://www.python.org/downloads/)
[](https://github.com/fxstein/ascii-guard/actions/workflows/ci.yml)
[](https://codecov.io/gh/fxstein/ascii-guard)
[](https://github.com/astral-sh/ruff)
[](https://mypy-lang.org/)
[](https://github.com/fxstein/ascii-guard/pulls)
---
## 🎯 Why ascii-guard?
AI-generated ASCII flowcharts and diagrams often have subtle formatting errors where box borders are misaligned by 1-2 characters. This breaks visual integrity and makes documentation harder to read.
**ascii-guard** automatically detects and fixes these alignment issues, ensuring your ASCII art looks perfect.
### ✨ Key Features
- 🚀 **Minimal dependencies** - Zero for Python 3.11+, one tiny dep for Python 3.10 (`tomli`)
- 💾 **Tiny footprint** - Lightweight and fast
- 🔒 **Minimal supply chain risk** - Pure stdlib on 3.11+
- ⚡ **Quick startup** - No import overhead
- 📦 **Simple installation** - One command, automatic dependency handling
- 🐍 **Python API** - Stable programmatic interface for integration into pipelines and scripts
- 🛡️ **Type-safe** - Full mypy strict mode
- ✅ **Well tested** - Comprehensive test coverage
---
## 📦 Installation
We recommend using `uv` for the fastest installation experience, but `pip` and `pipx` are fully supported alternatives. `uv` provides faster dependency resolution and better reproducibility, while `pip` and `pipx` work with any standard Python environment.
### Recommended: Using uv (Fastest)
```bash
# Install ascii-guard
uv tool install ascii-guard
```
> **Note:** If `uv` is not installed, you may install it with: `curl -LsSf https://astral.sh/uv/install.sh | sh`
### Alternative: Using pip
```bash
pip install ascii-guard
```
### Alternative: Using pipx (Isolated Environment)
```bash
pipx install ascii-guard
```
That's it! No other dependencies needed.
---
## 🚀 Quick Start
### Check files for ASCII art issues
```bash
ascii-guard lint README.md
ascii-guard lint docs/**/*.md
```
### Auto-fix alignment issues
```bash
ascii-guard fix README.md
ascii-guard fix --dry-run docs/guide.md # Preview changes first
```
### Example 1: Simple Box
**Before** (misaligned):
```
┌─────────────────────┐
│ Box Content │
└────────────────────┘ ← Missing one character!
```
**After** (fixed):
```
┌─────────────────────┐
│ Box Content │
└─────────────────────┘ ← Perfect alignment ✓
```
### Example 2: Flowchart
**Before** (multiple alignment issues):
```
┌──────────────┐
│ Start │
└──────┬───────┘
│
┌──────▼───────┐
│ Step │ ← Right border misaligned
└──────┬───────┘
│
┌──────▼───────┐
│ End ││ ← Duplicate right border
└────────────── ← Broken bottom right corner
```
**After** (all boxes aligned):
```
┌──────────────┐
│ Start │
└──────┬───────┘
│
┌──────▼───────┐
│ Step │
└──────┬───────┘
│
┌──────▼───────┐
│ End │
└──────────────┘
```
ascii-guard automatically detects and fixes alignment issues across multiple boxes, nested structures, and complex flowcharts.
---
## 🎭 Ignore Markers
Need to show intentionally broken boxes in your docs? Use ignore markers:
```markdown
**❌ Common Mistake (don't do this):**
┌─────────────────────┐
│ Box Content │
└────────────────────┘ ← Misaligned on purpose for demonstration
**✅ Correct Way:**
┌─────────────────────┐
│ Box Content │
└─────────────────────┘ ← Perfect alignment
```
The ignore markers are invisible in rendered markdown but tell ascii-guard to skip validation. Perfect for:
- Before/after comparisons
- Tutorial examples showing common mistakes
- Documentation with intentionally broken examples
See [USAGE.md](docs/USAGE.md#ignore-markers) for complete syntax and examples.
---
## 🎨 Supported Box-Drawing Characters
ascii-guard supports Unicode box-drawing characters:
| Type | Characters | Description |
|------|------------|-------------|
| **Horizontal** | `─` (U+2500) | Horizontal line |
| **Vertical** | `│` (U+2502) | Vertical line |
| **Corners** | `┌` `┐` `└` `┘` | Standard corners |
| **T-junctions** | `├` `┤` `┬` `┴` | Connection points |
| **Cross** | `┼` | Four-way intersection |
| **Heavy lines** | `━` `┃` `┏` `┓` `┗` `┛` | Bold variants |
| **Double lines** | `═` `║` `╔` `╗` `╚` `╝` | Double-line variants |
---
## 📋 Validation Rules
ascii-guard checks for:
1. **Vertical alignment** - All `│` characters in a column align
2. **Horizontal alignment** - All `─` characters connect properly
3. **Corner correctness** - Corner characters match adjacent lines
4. **Width consistency** - Top, middle, and bottom borders match
5. **Content fit** - Content stays within box borders
---
## 🐍 Python API
ascii-guard provides a stable Python API for programmatic use. Perfect for integrating into documentation pipelines, CI/CD scripts, or custom tooling.
```python
from ascii_guard import lint_file, fix_file, detect_boxes
# Lint a file for issues
result = lint_file("README.md")
if result.has_errors:
print(f"Found {len(result.errors)} alignment errors")
for error in result.errors:
print(f" Line {error.line + 1}: {error.message}")
# Auto-fix alignment issues
result = fix_file("README.md", dry_run=True) # Preview first
print(f"Would fix {result.boxes_fixed} boxes")
# Detect boxes without validation
boxes = detect_boxes("docs/guide.md")
print(f"Found {len(boxes)} ASCII art boxes")
```
**Available functions:**
- `lint_file()` - Lint a file for ASCII art alignment issues
- `fix_file()` - Fix alignment issues in a file
- `detect_boxes()` - Detect ASCII art boxes without validation
- `validate_box()` - Validate a single Box object
- `fix_box()` - Fix a single Box object
**Data models:** `Box`, `ValidationError`, `LintResult`, `FixResult`
> 📖 **Full API documentation**: See [API Reference](docs/API_REFERENCE.md) for complete details, type signatures, and advanced examples.
---
## 🤝 Contributing
We welcome contributions! Here's how to get started:
**Prerequisites:**
- Python 3.10+
- [uv](https://github.com/astral-sh/uv) - Fast Python package manager
```bash
# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh
# Fork and clone the repository
git clone https://github.com/YOUR-USERNAME/ascii-guard.git
cd ascii-guard
# One-step setup (creates venv, installs deps, configures hooks)
./setup.sh
# Use uv run for commands
uv run pytest # Run tests
uv run ruff check . # Lint code
uv run mypy src/ # Type check
# Make your changes and submit a PR
```
**For detailed development guide, see [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md)**
**For contribution guidelines, see [CONTRIBUTING.md](CONTRIBUTING.md)**
---
## 📄 License
Apache License 2.0 - see [LICENSE](LICENSE) for details.
Copyright 2025 Oliver Ratzesberger
---
## 🔗 Links
- **Repository**: https://github.com/fxstein/ascii-guard
- **Issues**: https://github.com/fxstein/ascii-guard/issues
- **PyPI**: https://pypi.org/project/ascii-guard/
- **Documentation**:
- [User Guide](docs/USAGE.md) - Complete usage documentation
- [Python API Reference](docs/API_REFERENCE.md) - Complete API documentation
- [Development Guide](docs/DEVELOPMENT.md) - Setup, workflow, architecture
- [FAQ](docs/FAQ.md) - Frequently asked questions
---
## 🙏 Acknowledgments
Inspired by the need for better ASCII art formatting in AI-generated documentation.
Built with ❤️ using only Python's standard library.
---
**Note**: ascii-guard is stable and actively maintained. Contributions and feedback are welcome!