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 unique filename in the documentation.

Wiki-link formats supported:
- [[filename]] - links to filename.md (must be unique across all docs)
- [[target|Display Text]] - filename with display text

Path-based links (containing '/') are NOT supported to ensure all
filenames are unique and links work correctly in obsidian.nvim.

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]]
# Captures: group(1) = target (may have spaces), group(2) = full "|Display" part if present
WIKILINK_PATTERN = re.compile(r"\[\[([^\]|]+)(\|[^\]]+)?\]\]")

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


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

    Returns list of (target, line_num, has_spaces) tuples.
    has_spaces is True if the target or pipe separator had surrounding spaces.

    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):
            raw_target = match.group(1)
            target = raw_target.strip()
            pipe_part = match.group(2)  # "|Display" or None
            # Check for spaces: in target, or around the pipe
            has_spaces = raw_target != target
            if pipe_part and (raw_target.endswith(" ") or pipe_part.startswith("| ")):
                has_spaces = True
            links.append((target, line_num, has_spaces))

    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, ambiguous, path-based, and spaced links
    broken_links: list[tuple[str, int, str]] = []
    ambiguous_links: list[tuple[str, int, str, list[str]]] = []
    path_links: list[tuple[str, int, str]] = []
    spaced_links: list[tuple[str, int, 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, has_spaces in links:
            if has_spaces:
                # Links with spaces in target or around pipe are not allowed
                spaced_links.append((rel_path, line_num, target))
            elif "/" in target:
                # Path-based links are not allowed - use simple filenames only
                path_links.append((rel_path, line_num, target))
            elif target in ambiguous_filenames:
                # Link uses an ambiguous filename - needs to be renamed
                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 spaced_links:
        has_errors = True
        console.print("[bold red]Wiki-Links With Spaces Found[/bold red]")
        console.print("Wiki-links must not have spaces in the target or around the pipe.")
        console.print("Use [[target|Display Text]] not [[target | Display Text]].")
        console.print()
        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 spaced_links:
            table.add_row(file_path, str(line_num), escape(f"[[{target}]]"))

        console.print(table)
        console.print()

    if path_links:
        has_errors = True
        console.print("[bold red]Path-Based Wiki-Links Found[/bold red]")
        console.print("Wiki-links must use simple filenames only (no '/' paths).")
        console.print("Rename files to be unique, then use [[filename]] format.")
        console.print()
        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 path_links:
            table.add_row(file_path, str(line_num), escape(f"[[{target}]]"))

        console.print(table)
        console.print()

    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("Rename files to be unique across all documentation.")
        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())