🛡️ LinkGuard

Fast, async link validation for developers. Catch broken links before your users do.

LinkGuard is a fast, async Python CLI tool that scans your project files for broken links and development URLs. Catch 404s before your users do, and ensure localhost references don't leak into production.

---

✨ Features

• 🚀 Blazing Fast - Async validation checks hundreds of links in seconds
• 🎯 Environment-Aware - Detect localhost/dev URLs that shouldn't reach production
• 🎨 Beautiful CLI - Rich progress bars and color-coded results
• 📊 Multiple Exports - JSON, CSV, and Markdown reports for automation
• 🔍 Smart Extraction - Supports Markdown, HTML, JSON, JS/TS, and plain text
• ⚙️ Zero Config - Works out of the box with sensible defaults
• 🛠️ Configurable - .linkguardignore and linkguard.config.json support
• ✅ Production Ready - 91 tests, 71% coverage, comprehensive documentation

---

📦 Installation

# Install from PyPI (coming soon)
pip install linkguard

# Or install from source
git clone https://github.com/anubhabx/link-guard.git
cd link-guard

# Create virtual environment
python -m venv venv

# Activate virtual environment
# Windows (PowerShell)
.\venv\Scripts\Activate.ps1
# Linux/Mac
source venv/bin/activate

# Install in development mode (includes all dependencies)
pip install -e ".[dev]"

💡 Tip: After installation with pip install -e ".[dev]", you can use linkguard directly instead of python -m linkguard.cli

---

🚀 Quick Start

# Scan current directory
linkguard

# Scan specific directory
linkguard ./docs

# Production mode (flags localhost URLs as errors)
linkguard --mode prod

# Export results to JSON
linkguard --export report.json

# Custom timeout
linkguard --timeout 15

Example Output:

🔍 Scanning directory: ./docs
Mode: dev | Timeout: 10s

✓ Found 42 files to scan
✓ Extracted 156 URLs

🌐 Checking links...
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100% 156/156

╭─ Scan Summary ─────────────╮
│ Files scanned       42     │
│ URLs found          156    │
│ Working links       152    │
│ Broken links        4      │
│ Rule violations     0      │
╰────────────────────────────╯

---

📖 Documentation

Document	Description
QUICKSTART.md	Installation, basic usage, and common examples
FEATURES.md	Complete feature list and capabilities
CONTRIBUTING.md	Development setup, testing, and contribution guidelines
RELEASE_NOTES.md	v1.0 release details and highlights
CHANGELOG.md	Full version history and changes

---

⚙️ Configuration

Command-Line Options

linkguard [DIRECTORY] [OPTIONS]

Options:
  --mode, -m          dev|prod        Scanning mode (default: dev)
  --timeout, -t       INTEGER         Request timeout in seconds (default: 10)
  --export, -e        PATH            Export to JSON/CSV/Markdown
  --concurrency, -c   INTEGER         Max concurrent requests (default: 50)
  --ignore, -i        TEXT            Comma-separated ignore patterns
  --verbose, -v                       Detailed output
  --help                              Show help

Configuration File

Create linkguard.config.json in your project root:

{
  "mode": "prod",
  "timeout": 15,
  "concurrency": 100,
  "ignore_patterns": ["node_modules/**", "*.min.js"],
  "exclude_urls": ["https://example.local"],
  "strict_ssl": false
}

See linkguard.config.json.example for all options.

Ignore File

Create .linkguardignore (gitignore-style syntax):

# Ignore directories
node_modules/
dist/**
build/

# Ignore file patterns
*.draft.md
temp-*.json

# Ignore domains
*.internal.company.com
example.local

---

🏗️ Supported File Types

Type	Extensions	What's Extracted
Markdown	.md, .markdown	[text](url) and bare URLs
HTML	.html, .htm	href, src attributes
JSON	.json	URL strings in values
JavaScript/TypeScript	.js, .jsx, .ts, .tsx	Bare URL patterns
Plain Text	.txt	HTTP/HTTPS URLs

Auto-excluded: .git, .venv, node_modules, __pycache__, dist, build

---

🔧 CI/CD Integration

GitHub Actions

name: Link Validation

on: [push, pull_request]

jobs:
  check-links:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-python@v4
        with:
          python-version: '3.10'
      - name: Install LinkGuard
        run: pip install linkguard
      - name: Check links
        run: linkguard --mode prod --export report.json
      - name: Upload report
        if: failure()
        uses: actions/upload-artifact@v3
        with:
          name: link-report
          path: report.json

Exit Codes:

• 0 - All links valid
• 1 - Broken links or rule violations found
• 2 - Configuration error

---

🎯 Use Cases

✅ Documentation Sites - Ensure all links work before publishing
✅ Open Source Projects - Validate README and wiki links
✅ Marketing Sites - Check landing pages and blog posts
✅ CI/CD Pipelines - Automated link checking on every commit
✅ Pre-Production Checks - Catch localhost URLs before deployment
✅ Content Migration - Validate links after CMS migrations

---

🤝 Contributing

We welcome contributions! See CONTRIBUTING.md for:

• Development setup and workflow
• Testing guidelines (91 tests, 71% coverage)
• Code style requirements (PEP 8, Black, type hints)
• Pull request process

Quick Start:

git clone https://github.com/anubhabx/link-guard.git
cd link-guard
python -m venv venv
source venv/bin/activate  # or .\venv\Scripts\Activate.ps1 on Windows
pip install -e ".[dev]"
pytest tests/ -v

---

🗺️ Roadmap

✅ v1.0 (Current - October 2025)

• Production-ready release
• Comprehensive documentation
• 91 passing tests with 71% coverage
• GitHub Actions CI/CD
• Published to PyPI

🚧 v1.1.0 (Planned)

• Retry logic with exponential backoff
• Custom HTTP headers support
• Relative URL resolution
• Enhanced performance optimizations

🔮 v2.0.0 (Future)

• Anchor link validation (#section)
• Browser automation (Playwright) for bot detection bypass
• Web dashboard for analytics
• Webhook notifications (Slack/Discord)

See FEATURES.MD for complete roadmap.

---

📊 Performance

Benchmarks (typical projects):

• ✅ 100 links validated in ~2 seconds
• ✅ 1,000 links validated in ~5 seconds
• ✅ 10,000 files scanned in <30 seconds

Architecture:

• Async I/O with aiohttp for concurrent requests
• Semaphore-based concurrency control (default: 50)
• Memory-efficient streaming file reads
• HEAD request with smart GET fallback

---

🐛 Troubleshooting

Valid links marked as broken?

• Some servers block automated requests → Increase timeout: --timeout 20

"Connection timeout" errors?

• Network latency or slow servers → Try: --timeout 30

Ignore specific files/URLs?

• Use .linkguardignore or add to linkguard.config.json

Command not found?

• Ensure installed: pip install -e ".[dev]"
• Or use: python -m linkguard.cli

SSL certificate errors?

• LinkGuard skips SSL verification by default
• Coming soon: --strict-ssl flag

See QUICKSTART.MD for more troubleshooting tips.

---

📄 License

MIT License - see LICENSE file for details.

---

🙏 Acknowledgments

Built with these amazing tools:

• aiohttp - Async HTTP client
• typer - Modern CLI framework
• rich - Beautiful terminal formatting
• beautifulsoup4 - HTML parsing

Special thanks to all contributors! 🎉

---

📞 Support

• 🐛 Bug Reports: GitHub Issues
• 💬 Discussions: GitHub Discussions
• 💡 Feature Requests: Open an Issue
• 📧 Contact: anubhabxdev@gmail.com

---