{"id":46511616,"url":"https://github.com/fxstein/ascii-guard","last_synced_at":"2026-03-06T16:31:01.017Z","repository":{"id":324526639,"uuid":"1097524477","full_name":"fxstein/ascii-guard","owner":"fxstein","description":"Zero-dependency Python linter for detecting and fixing misaligned AI ASCII art boxes in documentation","archived":false,"fork":false,"pushed_at":"2026-03-02T21:54:11.000Z","size":1168,"stargazers_count":17,"open_issues_count":5,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-03-03T00:38:16.836Z","etag":null,"topics":["agent","ai","cursor","python"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fxstein.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-16T10:54:31.000Z","updated_at":"2026-03-02T21:54:09.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/fxstein/ascii-guard","commit_stats":null,"previous_names":["fxstein/ascii-guard"],"tags_count":16,"template":false,"template_full_name":null,"purl":"pkg:github/fxstein/ascii-guard","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fxstein%2Fascii-guard","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fxstein%2Fascii-guard/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fxstein%2Fascii-guard/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fxstein%2Fascii-guard/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fxstein","download_url":"https://codeload.github.com/fxstein/ascii-guard/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fxstein%2Fascii-guard/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30185423,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-06T14:42:24.748Z","status":"ssl_error","status_checked_at":"2026-03-06T14:42:14.925Z","response_time":250,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent","ai","cursor","python"],"created_at":"2026-03-06T16:31:00.288Z","updated_at":"2026-03-06T16:31:00.990Z","avatar_url":"https://github.com/fxstein.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ascii-guard\n\n**Zero-dependency Python linter for detecting and fixing misaligned ASCII art boxes in documentation.**\n\n[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)\n[![Python](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)\n[![CI](https://github.com/fxstein/ascii-guard/actions/workflows/ci.yml/badge.svg)](https://github.com/fxstein/ascii-guard/actions/workflows/ci.yml)\n[![codecov](https://codecov.io/gh/fxstein/ascii-guard/branch/main/graph/badge.svg)](https://codecov.io/gh/fxstein/ascii-guard)\n[![Code style: ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)\n[![Type checked: mypy](https://img.shields.io/badge/type%20checked-mypy-blue.svg)](https://mypy-lang.org/)\n[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/fxstein/ascii-guard/pulls)\n\n---\n\n## 🎯 Why ascii-guard?\n\nAI-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.\n\n**ascii-guard** automatically detects and fixes these alignment issues, ensuring your ASCII art looks perfect.\n\n### ✨ Key Features\n\n- 🚀 **Minimal dependencies** - Zero for Python 3.11+, one tiny dep for Python 3.10 (`tomli`)\n- 💾 **Tiny footprint** - Lightweight and fast\n- 🔒 **Minimal supply chain risk** - Pure stdlib on 3.11+\n- ⚡ **Quick startup** - No import overhead\n- 📦 **Simple installation** - One command, automatic dependency handling\n- 🐍 **Python API** - Stable programmatic interface for integration into pipelines and scripts\n- 🛡️ **Type-safe** - Full mypy strict mode\n- ✅ **Well tested** - Comprehensive test coverage\n\n---\n\n## 📦 Installation\n\nWe 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.\n\n### Recommended: Using uv (Fastest)\n\n```bash\n# Install ascii-guard\nuv tool install ascii-guard\n```\n\n\u003e **Note:** If `uv` is not installed, you may install it with: `curl -LsSf https://astral.sh/uv/install.sh | sh`\n\n### Alternative: Using pip\n\n```bash\npip install ascii-guard\n```\n\n### Alternative: Using pipx (Isolated Environment)\n\n```bash\npipx install ascii-guard\n```\n\nThat's it! No other dependencies needed.\n\n---\n\n## 🚀 Quick Start\n\n### Check files for ASCII art issues\n\n```bash\nascii-guard lint README.md\nascii-guard lint docs/**/*.md\n```\n\n### Auto-fix alignment issues\n\n```bash\nascii-guard fix README.md\nascii-guard fix --dry-run docs/guide.md  # Preview changes first\n```\n\n### Example 1: Simple Box\n\n**Before** (misaligned):\n```\n┌─────────────────────┐\n│ Box Content         │\n└────────────────────┘   ← Missing one character!\n```\n\n**After** (fixed):\n```\n┌─────────────────────┐\n│ Box Content         │\n└─────────────────────┘  ← Perfect alignment ✓\n```\n\n### Example 2: Flowchart\n\n**Before** (multiple alignment issues):\n```\n┌──────────────┐\n│    Start     │\n└──────┬───────┘\n       │\n┌──────▼───────┐\n│    Step     │        ← Right border misaligned\n└──────┬───────┘\n       │\n┌──────▼───────┐\n│     End      ││      ← Duplicate right border\n└──────────────        ← Broken bottom right corner\n```\n\n**After** (all boxes aligned):\n```\n┌──────────────┐\n│    Start     │\n└──────┬───────┘\n       │\n┌──────▼───────┐\n│    Step      │\n└──────┬───────┘\n       │\n┌──────▼───────┐\n│     End      │\n└──────────────┘\n```\n\nascii-guard automatically detects and fixes alignment issues across multiple boxes, nested structures, and complex flowcharts.\n\n---\n\n## 🎭 Ignore Markers\n\nNeed to show intentionally broken boxes in your docs? Use ignore markers:\n\n```markdown\n**❌ Common Mistake (don't do this):**\n\n\u003c!-- ascii-guard-ignore-next --\u003e\n┌─────────────────────┐\n│ Box Content         │\n└────────────────────┘   ← Misaligned on purpose for demonstration\n\n**✅ Correct Way:**\n\n┌─────────────────────┐\n│ Box Content         │\n└─────────────────────┘  ← Perfect alignment\n```\n\nThe ignore markers are invisible in rendered markdown but tell ascii-guard to skip validation. Perfect for:\n- Before/after comparisons\n- Tutorial examples showing common mistakes\n- Documentation with intentionally broken examples\n\nSee [USAGE.md](docs/USAGE.md#ignore-markers) for complete syntax and examples.\n\n---\n\n## 🎨 Supported Box-Drawing Characters\n\nascii-guard supports Unicode box-drawing characters:\n\n| Type | Characters | Description |\n|------|------------|-------------|\n| **Horizontal** | `─` (U+2500) | Horizontal line |\n| **Vertical** | `│` (U+2502) | Vertical line |\n| **Corners** | `┌` `┐` `└` `┘` | Standard corners |\n| **T-junctions** | `├` `┤` `┬` `┴` | Connection points |\n| **Cross** | `┼` | Four-way intersection |\n| **Heavy lines** | `━` `┃` `┏` `┓` `┗` `┛` | Bold variants |\n| **Double lines** | `═` `║` `╔` `╗` `╚` `╝` | Double-line variants |\n\n---\n\n## 📋 Validation Rules\n\nascii-guard checks for:\n\n1. **Vertical alignment** - All `│` characters in a column align\n2. **Horizontal alignment** - All `─` characters connect properly\n3. **Corner correctness** - Corner characters match adjacent lines\n4. **Width consistency** - Top, middle, and bottom borders match\n5. **Content fit** - Content stays within box borders\n\n---\n\n## 🐍 Python API\n\nascii-guard provides a stable Python API for programmatic use. Perfect for integrating into documentation pipelines, CI/CD scripts, or custom tooling.\n\n```python\nfrom ascii_guard import lint_file, fix_file, detect_boxes\n\n# Lint a file for issues\nresult = lint_file(\"README.md\")\nif result.has_errors:\n    print(f\"Found {len(result.errors)} alignment errors\")\n    for error in result.errors:\n        print(f\"  Line {error.line + 1}: {error.message}\")\n\n# Auto-fix alignment issues\nresult = fix_file(\"README.md\", dry_run=True)  # Preview first\nprint(f\"Would fix {result.boxes_fixed} boxes\")\n\n# Detect boxes without validation\nboxes = detect_boxes(\"docs/guide.md\")\nprint(f\"Found {len(boxes)} ASCII art boxes\")\n```\n\n**Available functions:**\n- `lint_file()` - Lint a file for ASCII art alignment issues\n- `fix_file()` - Fix alignment issues in a file\n- `detect_boxes()` - Detect ASCII art boxes without validation\n- `validate_box()` - Validate a single Box object\n- `fix_box()` - Fix a single Box object\n\n**Data models:** `Box`, `ValidationError`, `LintResult`, `FixResult`\n\n\u003e 📖 **Full API documentation**: See [API Reference](docs/API_REFERENCE.md) for complete details, type signatures, and advanced examples.\n\n---\n\n## 🤝 Contributing\n\nWe welcome contributions! Here's how to get started:\n\n**Prerequisites:**\n- Python 3.10+\n- [uv](https://github.com/astral-sh/uv) - Fast Python package manager\n\n```bash\n# Install uv\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n\n# Fork and clone the repository\ngit clone https://github.com/YOUR-USERNAME/ascii-guard.git\ncd ascii-guard\n\n# One-step setup (creates venv, installs deps, configures hooks)\n./setup.sh\n\n# Use uv run for commands\nuv run pytest              # Run tests\nuv run ruff check .        # Lint code\nuv run mypy src/           # Type check\n\n# Make your changes and submit a PR\n```\n\n**For detailed development guide, see [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md)**\n\n**For contribution guidelines, see [CONTRIBUTING.md](CONTRIBUTING.md)**\n\n---\n\n## 📄 License\n\nApache License 2.0 - see [LICENSE](LICENSE) for details.\n\nCopyright 2025 Oliver Ratzesberger\n\n---\n\n## 🔗 Links\n\n- **Repository**: https://github.com/fxstein/ascii-guard\n- **Issues**: https://github.com/fxstein/ascii-guard/issues\n- **PyPI**: https://pypi.org/project/ascii-guard/\n- **Documentation**:\n  - [User Guide](docs/USAGE.md) - Complete usage documentation\n  - [Python API Reference](docs/API_REFERENCE.md) - Complete API documentation\n  - [Development Guide](docs/DEVELOPMENT.md) - Setup, workflow, architecture\n  - [FAQ](docs/FAQ.md) - Frequently asked questions\n\n---\n\n## 🙏 Acknowledgments\n\nInspired by the need for better ASCII art formatting in AI-generated documentation.\n\nBuilt with ❤️ using only Python's standard library.\n\n---\n\n**Note**: ascii-guard is stable and actively maintained. Contributions and feedback are welcome!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffxstein%2Fascii-guard","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffxstein%2Fascii-guard","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffxstein%2Fascii-guard/lists"}