Erich Blume
9630655cc9
- Convert all wiki-links from title-based to filename-based - Update doc-links to validate against filenames - Add doc-filenames task for duplicate filename detection - Consolidate doc hooks into single local block in pre-commit config Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
110 lines
3.5 KiB
Text
Executable file
110 lines
3.5 KiB
Text
Executable file
#!/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 filenames.
|
|
|
|
This script scans all markdown files in the docs/ directory (excluding
|
|
changelog.d/ and zk/), extracts wiki-links, and verifies each link target
|
|
exists as a filename in the documentation.
|
|
|
|
Wiki-link formats supported:
|
|
- [[filename]] - links to filename.md
|
|
- [[filename | Display Text]] - links to filename.md, displays "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 filenames
|
|
valid_filenames: set[str] = set()
|
|
|
|
# Scan all markdown files for filenames (excluding zk/ and changelog.d/)
|
|
for md_file in DOCS_DIR.rglob("*.md"):
|
|
if "changelog.d" in md_file.parts or "zk" in md_file.parts:
|
|
continue
|
|
valid_filenames.add(md_file.stem)
|
|
|
|
# Collect all broken links
|
|
broken_links: list[tuple[str, int, str]] = []
|
|
|
|
# Scan all markdown files for wiki-links (excluding zk/ and changelog.d/)
|
|
for md_file in sorted(DOCS_DIR.rglob("*.md")):
|
|
if "changelog.d" in md_file.parts or "zk" 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 not in valid_filenames:
|
|
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_filenames)} valid filenames in documentation.")
|
|
console.print()
|
|
|
|
if broken_links:
|
|
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(f"[bold red]{len(broken_links)} broken link(s) found.[/bold red]")
|
|
console.print()
|
|
console.print("Each wiki-link target must match a filename in docs/.")
|
|
return 1
|
|
|
|
console.print("[bold green]All wiki-links are valid![/bold green]")
|
|
return 0
|
|
|
|
|
|
if __name__ == "__main__":
|
|
sys.exit(main())
|