blumeops/mise-tasks/doc-links

#!/usr/bin/env -S uv run --script
# /// script
# requires-python = ">=3.12"
# dependencies = ["rich>=13.0.0"]
# ///
#MISE description="Validate all wiki-links point to existing doc filenames"
"""Validate that all wiki-links in documentation point to existing files.

This script scans all markdown files in the docs/ directory (excluding
changelog.d/), extracts wiki-links, and verifies each link target
exists as a filename or path in the documentation.

Wiki-link formats supported:
- [[filename]] - links to filename.md (must be unique)
- [[path/to/file]] - links to path/to/file.md (for ambiguous filenames like index)
- [[target | Display Text]] - either format with display text

Usage: mise run doc-links
"""

import re
import sys
from pathlib import Path

from rich.console import Console
from rich.markup import escape
from rich.table import Table

DOCS_DIR = Path(__file__).parent.parent / "docs"

# Regex to match wiki-links: [[Target]] or [[Target | Display]]
WIKILINK_PATTERN = re.compile(r"\[\[([^\]|]+)(?:\s*\|\s*[^\]]+)?\]\]")

# Regex to match inline code (backticks)
INLINE_CODE_PATTERN = re.compile(r"`[^`]+`")


def extract_wikilinks(file_path: Path) -> list[tuple[str, int]]:
    """Extract all wiki-link targets from a markdown file with line numbers.

    Ignores wiki-links inside inline code (backticks) as these are examples.
    """
    content = file_path.read_text()
    links = []

    for line_num, line in enumerate(content.splitlines(), start=1):
        # Remove inline code before searching for wiki-links
        line_without_code = INLINE_CODE_PATTERN.sub("", line)
        for match in WIKILINK_PATTERN.finditer(line_without_code):
            target = match.group(1).strip()
            links.append((target, line_num))

    return links


def main() -> int:
    console = Console()

    # Collect all valid targets (both filenames and paths)
    valid_targets: set[str] = set()
    # Track which filenames are ambiguous (appear multiple times)
    filename_counts: dict[str, list[str]] = {}

    # Scan all markdown files (excluding changelog.d/)
    for md_file in DOCS_DIR.rglob("*.md"):
        if "changelog.d" in md_file.parts:
            continue
        # Track filename occurrences
        filename = md_file.stem
        rel_path_str = str(md_file.relative_to(DOCS_DIR).with_suffix(""))
        if filename not in filename_counts:
            filename_counts[filename] = []
        filename_counts[filename].append(rel_path_str)
        # Add relative path without extension (e.g., "reference/services/alloy")
        valid_targets.add(rel_path_str)

    # Only add filenames that are unique (not ambiguous)
    ambiguous_filenames: set[str] = set()
    for filename, paths in filename_counts.items():
        if len(paths) == 1:
            valid_targets.add(filename)
        else:
            ambiguous_filenames.add(filename)

    # Special case: files at repo root that are copied into docs during build
    # These are valid link targets even though they don't exist in docs/
    REPO_ROOT = DOCS_DIR.parent
    BUILD_TIME_DOCS = ["CHANGELOG.md"]
    for filename in BUILD_TIME_DOCS:
        if (REPO_ROOT / filename).exists():
            valid_targets.add(Path(filename).stem)

    # Collect all broken and ambiguous links
    broken_links: list[tuple[str, int, str]] = []
    ambiguous_links: list[tuple[str, int, str, list[str]]] = []

    # Scan all markdown files for wiki-links (excluding changelog.d/)
    for md_file in sorted(DOCS_DIR.rglob("*.md")):
        if "changelog.d" in md_file.parts:
            continue

        rel_path = str(md_file.relative_to(DOCS_DIR))
        links = extract_wikilinks(md_file)

        for target, line_num in links:
            if target in ambiguous_filenames:
                # Link uses an ambiguous filename - needs to use full path
                ambiguous_links.append((rel_path, line_num, target, filename_counts[target]))
            elif target not in valid_targets:
                broken_links.append((rel_path, line_num, target))

    # Print results
    console.print("[bold]Wiki-Link Validation[/bold]")
    console.print()
    console.print(f"Found {len(valid_targets)} valid link targets in documentation.")
    console.print()

    has_errors = False

    if ambiguous_links:
        has_errors = True
        console.print("[bold red]Ambiguous Wiki-Links Found[/bold red]")
        console.print("These links use filenames that exist in multiple locations.")
        console.print("Use the full path instead (e.g., [[reference/index]] not [[index]]).")
        console.print()
        table = Table(show_header=True, header_style="bold")
        table.add_column("File")
        table.add_column("Line", justify="right")
        table.add_column("Target")
        table.add_column("Possible Paths")

        for file_path, line_num, target, paths in ambiguous_links:
            table.add_row(file_path, str(line_num), escape(f"[[{target}]]"), "\n".join(paths))

        console.print(table)
        console.print()

    if broken_links:
        has_errors = True
        console.print("[bold red]Broken Wiki-Links Found[/bold red]")
        table = Table(show_header=True, header_style="bold")
        table.add_column("File")
        table.add_column("Line", justify="right")
        table.add_column("Target")

        for file_path, line_num, target in broken_links:
            table.add_row(file_path, str(line_num), escape(f"[[{target}]]"))

        console.print(table)
        console.print()
        console.print("Each wiki-link target must match a filename or path in docs/.")
        console.print()

    if has_errors:
        return 1

    console.print("[bold green]All wiki-links are valid![/bold green]")
    return 0


if __name__ == "__main__":
    sys.exit(main())