Fix reference/index wiki-link and support path-based links in doc-links

- Use [[reference/index | reference]] for ambiguous index.md link
- Update doc-links to validate both filenames and paths

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

mise-tasks/doc-links

@@ -4,15 +4,16 @@
 # 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.
+"""Validate that all wiki-links in documentation point to existing files.
 
 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.
+exists as a filename or path in the documentation.
 
 Wiki-link formats supported:
-- [[filename]] - links to filename.md
-- [[filename | Display Text]] - links to filename.md, displays "Display Text"
+- [[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
 """
@@ -55,17 +56,35 @@ def extract_wikilinks(file_path: Path) -> list[tuple[str, int]]:
 def main() -> int:
     console = Console()
 
-    # Collect all valid filenames
-    valid_filenames: set[str] = set()
+    # 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 for filenames (excluding zk/ and changelog.d/)
+    # Scan all markdown files (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)
+        # 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)
 
-    # Collect all broken links
+    # 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)
+
+    # 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 zk/ and changelog.d/)
     for md_file in sorted(DOCS_DIR.rglob("*.md")):
@@ -76,16 +95,40 @@ def main() -> int:
         links = extract_wikilinks(md_file)
 
         for target, line_num in links:
-            if target not in valid_filenames:
+            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_filenames)} valid filenames in documentation.")
+    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")
@@ -97,9 +140,10 @@ def main() -> int:
 
         console.print(table)
         console.print()
-        console.print(f"[bold red]{len(broken_links)} broken link(s) found.[/bold red]")
+        console.print("Each wiki-link target must match a filename or path in docs/.")
         console.print()
-        console.print("Each wiki-link target must match a filename in docs/.")
+
+    if has_errors:
         return 1
 
     console.print("[bold green]All wiki-links are valid![/bold green]")