deadlinkfinder 0.2.3

  ██████╗ ███████╗ █████╗ ██████╗ ██╗     ██╗███╗   ██╗██╗  ██╗
  ██╔══██╗██╔════╝██╔══██╗██╔══██╗██║     ██║████╗  ██║██║ ██╔╝
  ██║  ██║█████╗  ███████║██║  ██║██║     ██║██╔██╗ ██║█████╔╝ 
  ██║  ██║██╔══╝  ██╔══██║██║  ██║██║     ██║██║╚██╗██║██╔═██╗ 
  ██████╔╝███████╗██║  ██║██████╔╝███████╗██║██║ ╚████║██║  ██╗
  ╚═════╝ ╚══════╝╚═╝  ╚═╝╚═════╝ ╚══════╝╚═╝╚═╝  ╚═══╝╚═╝  ╚═╝
                 ███████╗██╗███╗   ██╗██████╗ ███████╗██████╗  
                 ██╔════╝██║████╗  ██║██╔══██╗██╔════╝██╔══██╗ 
                 █████╗  ██║██╔██╗ ██║██║  ██║█████╗  ██████╔╝ 
                 ██╔══╝  ██║██║╚██╗██║██║  ██║██╔══╝  ██╔══██╗ 
                 ██║     ██║██║ ╚████║██████╔╝███████╗██║  ██║ 
                 ╚═╝     ╚═╝╚═╝  ╚═══╝╚═════╝ ╚══════╝╚═╝  ╚═╝ 
  ───────🔗 Documentation Link Graph & GFM Anchor Integrity Verifier 🔍───────

⚡ Instant Quickstart

Run immediately on any repository without installing via uvx:

# Scan all Markdown (.md) and reStructuredText (.rst) files in current repo (100% offline)
uvx deadlinkfinder .

# Export OASIS SARIF v2.1.0 report with partialFingerprints for GitHub Code Scanning
uvx deadlinkfinder --format sarif -o deadlinks.sarif docs/

# Export machine-parseable JSON report for custom CI pipelines
uvx deadlinkfinder --format json -o deadlinks.json .

# Optionally validate external HTTP/HTTPS URLs with a 5-second timeout
uvx deadlinkfinder --check-external --timeout 5.0 docs/

Or install globally via pip or pipx:

pip install deadlinkfinder
# or
pipx install deadlinkfinder

💥 Problem vs. Solution

The Pain with Traditional Link Checkers

• Silent #heading-anchor Breakage: A contributor renames ## 🚀 Setup & Keys to ## Authentication, silently breaking 12 cross-file [setup](docs/api.md#setup--keys) links. Traditional file-only checkers pass because docs/api.md still exists.
• Flaky External Rate-Limit Failures: Network-first link checkers hammer GitHub, LinkedIn, and Cloudflare-protected URLs on every Pull Request, failing CI builds randomly due to HTTP 429 Too Many Requests.
• Blind to reStructuredText & Sphinx: Most lightweight link checkers only parse basic Markdown [text](url), completely ignoring .rst files, .. image:: directives, and Sphinx doc / ref roles common in Python ecosystems.
• False Positives in Code Tutorials: Naive regex linters flag sample URLs and placeholder links inside fenced code blocks or inline code spans ([example](fake.md)).

Character-Aligned Before vs. After

┌───────────────────────────────────────────────────┬───────────────────────────────────────────────────┐
│ BEFORE: Silent 404s, Broken #heading-anchors      │ AFTER: DeadLinkFinder Offline Link Graph          │
│         & Missing Docs Assets                     │        & Fuzzy Suggestions                        │
├───────────────────────────────────────────────────┼───────────────────────────────────────────────────┤
│ $ git mv docs/setup.md docs/installation.md       │ $ deadlinkfinder docs/                            │
│ $ git commit -m "refactor: reorganize docs"       │                                                   │
│                                                   │ 🔗 DeadLinkFinder Verification Report             │
│ * PR merges cleanly (no link graph gate in CI).   │   Files Scanned:   14 (.md, .rst)                 │
│ * Users click "Getting Started" in README.md:     │   Links Checked:   128 local & #anchor refs       │
│   -> GitHub 404 Page Not Found!                   │ ───────────────────────────────────────────────── │
│ * Users click "[Auth Keys](api.md#auth-keys)":    │ [!] FAILED: Found 3 broken link(s):               │
│   -> Lands at top of page; section was renamed.   │                                                   │
│ * Architecture diagram path had a case typo:      │   ✗ [DLF-001] Broken Local File Link              │
│   -> Broken image icon rendered on PyPI & GitHub. │     Location:   docs/getting-started.md:28        │
│ * Team tries adding a traditional link checker:   │     Target:     '../guides/setup.md'              │
│   -> Installs 280MB of Node/Ruby dependencies.    │     Suggestion: Did you mean                      │
│   -> CI takes 45s and fails on HTTP 429 rate      │                 'docs/guides/installation.md'?    │
│      limits from external websites.               │                                                   │
│                                                   │   ✗ [DLF-002] Missing Anchor Slug                 │
│                                                   │     Location:   docs/api-reference.md:104         │
│                                                   │     Reason:     Anchor '#auth-keys' not found     │
│                                                   │                                                   │
│                                                   │   ✗ [DLF-004] Missing Local Image                 │
│                                                   │     Location:   docs/index.rst:42                 │
│                                                   │     Target:     './assets/arch-diagram.svg'       │
└───────────────────────────────────────────────────┴───────────────────────────────────────────────────┘

📝 Markdown & reStructuredText Coverage

DeadLinkFinder natively understands both GitHub Flavored Markdown (.md, .markdown) and reStructuredText / Sphinx (.rst) in a single unified pass:

🔍 Validation Rules

Every finding emits a permanent, deterministic Rule ID and SHA-256 partialFingerprints.primaryLocationLineHash (rule_id | path | line | target) for zero-noise CI/CD and GitHub Code Scanning deduplication:

📊 Competitive Comparison Matrix

🛠️ Production Quickstarts & Recipes

1. Instant Zero-Install Scan via uvx

# Verify entire repository offline
uvx deadlinkfinder .

# Scan only specific documentation folders and files
uvx deadlinkfinder README.md docs/ guides/

2. Standard pip Installation & CLI Usage

pip install deadlinkfinder

# Human-readable terminal report (disable ANSI colors for plain logs)
deadlinkfinder --no-color docs/

# Quiet mode: only emit output when broken links are detected
deadlinkfinder --quiet .

3. Pre-commit Hook Integration

Catch broken links, missing images, and dead #heading-anchors before git commit completes. Add to .pre-commit-config.yaml:

repos:
  - repo: https://github.com/umutgungorr/deadlinkfinder
    rev: v0.2.3
    hooks:
      - id: deadlinkfinder

4. CLI Reference

usage: deadlinkfinder [-h] [--version] [--format {text,json,sarif}] [-o OUTPUT]
                      [--check-external] [--offline] [--timeout TIMEOUT]
                      [--no-color] [-q] [-v]
                      [paths ...]

DeadLinkFinder: Zero-dependency Markdown link, image, and heading anchor verifier with SARIF support.

positional arguments:
  paths                 Markdown files or directories to scan (default: current directory)

options:
  -h, --help            show this help message and exit
  --version             show program's version number and exit
  --format {text,json,sarif}
                        Report format: text (human readable), json (machine parseable), sarif (GitHub Code Scanning)
  -o, --output OUTPUT   Write report output to specified file path instead of stdout
  --check-external      Check external HTTP/HTTPS links over network (default: local and anchor links only)
  --offline             Force offline mode: skip all external HTTP/HTTPS requests (default)
  --timeout TIMEOUT     HTTP request timeout in seconds for external URLs (default: 5.0)
  --no-color            Disable ANSI color codes in console output
  -q, --quiet           Quiet mode: suppress scan headers and only print detected errors
  -v, --verbose         Verbose diagnostic output

Deterministic Exit Codes:

• 0: Clean — all verified links, images, and #heading-anchors resolved.
• 1: Broken references detected (DLF-001 through DLF-007).
• 2: CLI usage error or target scan path does not exist.

🤖 GitHub Actions & SARIF Code Scanning

Option A: Marketplace Composite Action (Fastest PR Gate)

Drop DeadLinkFinder directly into .github/workflows/docs-links.yml:

name: Documentation Link Graph

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  verify-docs:
    runs-on: ubuntu-latest
    steps:
      - name: Check out repository
        uses: actions/checkout@v4

      - name: Run DeadLinkFinder Action
        uses: umutgungorr/deadlinkfinder@v1
        with:
          format: 'text'
          paths: '.'

Option B: GitHub Code Scanning SARIF Upload (Inline PR Annotations)

Generate OASIS SARIF v2.1.0 with deterministic partialFingerprints so GitHub annotates the exact broken Markdown or .rst line inside Pull Requests:

name: Docs SARIF Code Scanning

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

permissions:
  contents: read
  security-events: write

jobs:
  sarif-link-scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Run DeadLinkFinder (SARIF v2.1.0)
        uses: umutgungorr/deadlinkfinder@v1
        continue-on-error: true
        with:
          format: 'sarif'
          output: 'results.sarif'
          paths: '.'

      - name: Upload SARIF to GitHub Code Scanning
        uses: github/codeql-action/upload-sarif@v3
        if: always()
        with:
          sarif_file: results.sarif

🔬 Pipeline Architecture

┌───────────────────────────┐       ┌───────────────────────────┐
│   Markdown Files (.md)    │       │  reStructuredText (.rst)  │
│  GFM Links, Images, HTML  │       │  Directives & Sphinx Roles│
└─────────────┬─────────────┘       └─────────────┬─────────────┘
              │                                   │
              └─────────────────┬─────────────────┘
                                ▼
        ┌───────────────────────────────────────────────┐
        │         Code-Isolated Link Extractor          │
        │  * Strips fenced blocks (``` / ~~~)           │
        │  * Strips RST .. code-block:: & :: literals   │
        │  * Strips inline spans (`...` & ``...``)      │
        └───────────────────────┬───────────────────────┘
                                │
                                ▼
        ┌───────────────────────────────────────────────┐
        │     Link Graph & GFM Anchor Slug Verifier     │
        │  * Resolves relative paths & .rst extensions  │
        │  * Per-file cached HeadingTracker (-1, -2)    │
        │  * Fuzzy path suggestions via difflib         │
        │  * Optional cached HTTP/HTTPS URL verifier    │
        └───────────┬───────────────────┬───────────────┘
                    │                   │
       ┌────────────┘                   └────────────┐
       ▼                                             ▼
┌─────────────────────────────┐       ┌─────────────────────────────┐
│  Terminal / JSON Reporter   │       │   OASIS SARIF v2.1.0 Engine │
│  * ANSI diagnostics         │       │  * Rules DLF-001 .. DLF-007 │
│  * Did-you-mean hints       │       │  * SHA-256 Line Fingerprints│
│  * Exit Codes (0 / 1 / 2)   │       │  * GitHub Code Scanning     │
└─────────────────────────────┘       └─────────────────────────────┘

🚀 Verified Benchmarks

Measured on standard developer hardware (AMD Ryzen 9 / Apple M-series, offline mode):

🧪 Test Suite

DeadLinkFinder is verified across Python 3.9, 3.10, 3.11, 3.12, 3.13, and 3.14 on Linux, Windows, and macOS:

# Run full contract and unit test suite
uv run --with pytest pytest contract_tests tests -v

============================= test session starts =============================
platform win32 / linux / darwin -- Python 3.9 - 3.14
collected 32 items

contract_tests/test_contract.py ..                                       [  6%]
tests/test_cli.py ........                                               [ 31%]
tests/test_extractor.py ..........                                       [ 62%]
tests/test_slug.py ....                                                  [ 75%]
tests/test_verifier.py ........                                          [100%]

============================= 32 passed in 0.14s ==============================

🤝 Contributing

Contributions, bug reports, and edge-case fixtures are warmly welcomed! Please review:

• Contributing Guide
• Code of Conduct
• Changelog
• Security Policy

⚡ Part of the Developer Diagnostics Suite

DeadLinkFinder is a core pillar of the zero-dependency Developer Diagnostics Suite by @umutgungorr:

• 🌲 PortTree: Dev socket tree scanner, Docker proxy unmasker, and process-tree killer.
• ⚡ LogShrink: Zero-config CLI stream filter that collapses noisy polling logs and auto-boxes stack traces.
• 🩺 RepoPulse: Git forensic health, architectural hotspot churn, and bus-factor risk engine.
• 💊 EnvDoctor: Zero-dependency .env drift synchronizer, secret-safe generator, and codebase config auditor.
• 🔗 DeadLinkFinder: Offline Markdown & reStructuredText link graph, image asset, and GFM #heading-anchor verifier with SARIF v2.1.0 output.
• 🛡️ TokenGuard: Pre-commit secret scanner, entropy analyzer, and live credential leak blocker.

📖 Project Case Study

DeadLinkFinder is an open-source project by Umut Güngör. Read the DeadLinkFinder case study for its link graph architecture, GFM slug compatibility fixtures, and SARIF fingerprinting design.

📄 License

This project is licensed under the terms of the MIT License.
Copyright (c) 2026 Umut Güngör.