Skip to content

Switchyard lets LLM applications route traffic across models and providers while preserving native OpenAI and Anthropic API compatibility - enabling flexible model selection, benchmarking, and cost/performance optimization.

Rust
7.0 KB
Raw Blame
# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
# SPDX-License-Identifier: Apache-2.0

"""Tests for repository-relative links in MkDocs pages."""

import re
from pathlib import Path
from types import SimpleNamespace

from mkdocs_hooks import on_page_markdown, rewrite_repository_links

REPO_ROOT = Path(__file__).resolve().parents[1]
REPO_URL = "https://github.com/example/switchyard"
SOURCE_REF = "docs-ref"


class _Config(dict[str, object]):
    def __init__(self, repo_root: Path, docs_dir: Path) -> None:
        super().__init__(
            docs_dir=str(docs_dir),
            repo_url=REPO_URL,
            extra={"source_ref": SOURCE_REF},
        )
        self.config_file_path = str(repo_root / "mkdocs.yml")


def _repository(
    tmp_path: Path, page_relative_path: str = "docs/guides/page.md"
) -> tuple[Path, Path, Path]:
    repo_root = tmp_path / "repo"
    docs_dir = repo_root / "docs"
    page_path = repo_root / page_relative_path
    page_path.parent.mkdir(parents=True)
    page_path.write_text("# Page\n", encoding="utf-8")
    (repo_root / "AGENTS.md").write_text("# Instructions\n", encoding="utf-8")
    (repo_root / "examples" / "prometheus").mkdir(parents=True)
    (docs_dir / "index.md").write_text("# Home\n", encoding="utf-8")
    return repo_root, docs_dir, page_path


def _rewrite(markdown: str, repo_root: Path, docs_dir: Path, page_path: Path) -> str:
    return rewrite_repository_links(
        markdown,
        source_path=page_path,
        docs_dir=docs_dir,
        repo_root=repo_root,
        repo_url=REPO_URL,
        source_ref=SOURCE_REF,
    )


def test_repository_file_and_directory_links_use_blob_and_tree_urls(tmp_path: Path) -> None:
    repo_root, docs_dir, page_path = _repository(tmp_path)
    markdown = "[file](../../AGENTS.md)\n[directory](../../examples/prometheus/)\n"

    rewritten = _rewrite(markdown, repo_root, docs_dir, page_path)

    assert rewritten == (
        f"[file]({REPO_URL}/blob/{SOURCE_REF}/AGENTS.md)\n"
        f"[directory]({REPO_URL}/tree/{SOURCE_REF}/examples/prometheus)\n"
    )


def test_hook_resolves_links_from_a_nested_page_and_uses_mkdocs_config(tmp_path: Path) -> None:
    repo_root, docs_dir, page_path = _repository(tmp_path, "docs/routing/deep/page.md")
    page = SimpleNamespace(file=SimpleNamespace(abs_src_path=str(page_path)))

    rewritten = on_page_markdown(
        "[instructions](../../../AGENTS.md)",
        page=page,
        config=_Config(repo_root, docs_dir),
        files=object(),
    )

    assert rewritten == f"[instructions]({REPO_URL}/blob/{SOURCE_REF}/AGENTS.md)"


def test_repository_links_preserve_query_strings_and_fragments(tmp_path: Path) -> None:
    repo_root, docs_dir, page_path = _repository(tmp_path)

    rewritten = _rewrite(
        "[instructions](../../AGENTS.md?plain=1&view=raw#setup)",
        repo_root,
        docs_dir,
        page_path,
    )

    assert rewritten == (
        f"[instructions]({REPO_URL}/blob/{SOURCE_REF}/AGENTS.md?plain=1&view=raw#setup)"
    )


def test_repository_links_in_fenced_code_blocks_are_not_rewritten(tmp_path: Path) -> None:
    repo_root, docs_dir, page_path = _repository(tmp_path)
    markdown = (
        "```markdown\n"
        "[backtick fence](../../AGENTS.md)\n"
        "```\n"
        "~~~markdown\n"
        "[tilde fence](../../AGENTS.md)\n"
        "~~~\n"
        "[live link](../../AGENTS.md)\n"
    )

    rewritten = _rewrite(markdown, repo_root, docs_dir, page_path)

    assert rewritten == markdown.replace(
        "[live link](../../AGENTS.md)",
        f"[live link]({REPO_URL}/blob/{SOURCE_REF}/AGENTS.md)",
    )


def test_repository_links_in_blockquote_fences_are_not_rewritten(tmp_path: Path) -> None:
    repo_root, docs_dir, page_path = _repository(tmp_path)
    markdown = (
        "> ~~~markdown\n"
        "> [fenced link](../../AGENTS.md)\n"
        "> ~~~\n"
        "> Ordinary prose with ~~~ inline.\n"
        "> [live link](../../AGENTS.md)\n"
    )

    rewritten = _rewrite(markdown, repo_root, docs_dir, page_path)

    assert rewritten == markdown.replace(
        "[live link](../../AGENTS.md)",
        f"[live link]({REPO_URL}/blob/{SOURCE_REF}/AGENTS.md)",
    )


def test_repository_links_in_list_item_fences_are_not_rewritten(tmp_path: Path) -> None:
    repo_root, docs_dir, page_path = _repository(tmp_path)
    markdown = (
        "- Example:\n"
        "\n"
        "    ~~~markdown\n"
        "    [fenced link](../../AGENTS.md)\n"
        "    ~~~\n"
        "\n"
        "    Ordinary prose with ~~~ inline.\n"
        "    [live link](../../AGENTS.md)\n"
    )

    rewritten = _rewrite(markdown, repo_root, docs_dir, page_path)

    assert rewritten == markdown.replace(
        "[live link](../../AGENTS.md)",
        f"[live link]({REPO_URL}/blob/{SOURCE_REF}/AGENTS.md)",
    )


def test_indented_fence_markers_do_not_hide_outdented_prose_links(tmp_path: Path) -> None:
    repo_root, docs_dir, page_path = _repository(tmp_path)
    markdown = (
        "    ~~~\n"
        "[live link](../../AGENTS.md)\n"
        "    ~~~\n"
    )

    rewritten = _rewrite(markdown, repo_root, docs_dir, page_path)

    assert rewritten == markdown.replace(
        "[live link](../../AGENTS.md)",
        f"[live link]({REPO_URL}/blob/{SOURCE_REF}/AGENTS.md)",
    )


def test_missing_repository_target_remains_relative(tmp_path: Path) -> None:
    repo_root, docs_dir, page_path = _repository(tmp_path)
    markdown = "[missing](../../missing.md?plain=1#section)"

    assert _rewrite(markdown, repo_root, docs_dir, page_path) == markdown


def test_existing_target_outside_repository_remains_relative(tmp_path: Path) -> None:
    repo_root, docs_dir, page_path = _repository(tmp_path)
    (tmp_path / "outside.md").write_text("# Outside\n", encoding="utf-8")
    markdown = "[outside](../../../outside.md)"

    assert _rewrite(markdown, repo_root, docs_dir, page_path) == markdown


def test_links_inside_docs_dir_and_non_relative_links_are_unchanged(tmp_path: Path) -> None:
    repo_root, docs_dir, page_path = _repository(tmp_path)
    markdown = (
        "[docs page](../index.md)\n"
        "[external](https://example.com/docs)\n"
        "[page anchor](#section)\n"
    )

    assert _rewrite(markdown, repo_root, docs_dir, page_path) == markdown


def test_docs_do_not_hard_code_same_repository_blob_or_tree_links() -> None:
    config = (REPO_ROOT / "mkdocs.yml").read_text(encoding="utf-8")
    repo_url_match = re.search(r"^repo_url:\s*(\S+)\s*$", config, flags=re.MULTILINE)
    assert repo_url_match is not None
    repo_url = repo_url_match.group(1).strip("'\"").rstrip("/")
    source_link = re.compile(rf"{re.escape(repo_url)}/(?:blob|tree)/")
    markdown_paths = [REPO_ROOT / "README.md", *(REPO_ROOT / "docs").rglob("*.md")]

    offenders = [
        f"{path.relative_to(REPO_ROOT)}:{line_number}: {line.strip()}"
        for path in markdown_paths
        for line_number, line in enumerate(path.read_text(encoding="utf-8").splitlines(), start=1)
        if source_link.search(line)
    ]

    assert not offenders, "Hard-coded same-repository source links:\n" + "\n".join(offenders)