Skip to content

A visual, example-driven guide to Claude Code — from basic concepts to advanced agents, with copy-paste templates that bring immediate value.

3.8 KB
Raw Blame
"""Tests for check_cross_references.py — focus on repo-root boundary."""

from __future__ import annotations

import os
import sys
from pathlib import Path

import pytest

sys.path.insert(0, str(Path(__file__).parent.parent))

import check_cross_references


@pytest.fixture
def repo(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> Path:
    monkeypatch.chdir(tmp_path)
    return tmp_path


def test_links_escaping_repo_root_are_skipped(
    repo: Path, capsys: pytest.CaptureFixture[str]
) -> None:
    outside = repo.parent / "outside.md"
    outside.write_text("# Outside")

    rel = os.path.relpath(outside, repo)
    (repo / "README.md").write_text(f"# Doc\n\n[escape]({rel})\n")

    assert check_cross_references.main() == 0
    assert "broken cross-reference" not in capsys.readouterr().out


def test_broken_in_repo_link_is_reported(
    repo: Path, capsys: pytest.CaptureFixture[str]
) -> None:
    (repo / "README.md").write_text("# Doc\n\n[missing](does-not-exist.md)\n")

    assert check_cross_references.main() == 1
    assert "broken cross-reference" in capsys.readouterr().out


def test_valid_in_repo_link_passes(
    repo: Path, capsys: pytest.CaptureFixture[str]
) -> None:
    (repo / "other.md").write_text("# Other")
    (repo / "README.md").write_text("# Doc\n\n[ok](other.md)\n")

    assert check_cross_references.main() == 0
    assert "All cross-references valid" in capsys.readouterr().out


def test_numbered_lesson_dir_missing_readme_is_reported(
    repo: Path, capsys: pytest.CaptureFixture[str]
) -> None:
    (repo / "README.md").write_text("# Doc")
    (repo / "01-intro").mkdir()

    assert check_cross_references.main() == 1
    assert "01-intro: missing README.md" in capsys.readouterr().out


# U+200C ZERO WIDTH NON-JOINER: Persian uses it inside words, and GitHub keeps
# it in heading ids (e.g. the rendered fa/STYLE_GUIDE.md in PR #208). Spelled as
# escapes so editors can't strip them silently.
ZWNJ = "\u200c"
ZWJ = "\u200d"
PERSIAN_HEADING = f"نام{ZWNJ}گذاری فایل و پوشه"
PERSIAN_ANCHOR = f"نام{ZWNJ}گذاری-فایل-و-پوشه"


def test_heading_anchor_keeps_zero_width_non_joiner() -> None:
    assert check_cross_references.heading_to_anchor(PERSIAN_HEADING) == PERSIAN_ANCHOR


def test_heading_anchor_still_strips_em_dash_and_zero_width_joiner() -> None:
    assert (
        check_cross_references.heading_to_anchor("[v2.1.245] — 2026-08-25")
        == "v21245--2026-08-25"
    )
    assert check_cross_references.heading_to_anchor(f"A{ZWJ}B test") == "ab-test"


@pytest.mark.parametrize(
    ("heading", "anchor"),
    [
        ("Hướng dẫn bắt đầu nhanh", "hướng-dẫn-bắt-đầu-nhanh"),
        ("快速入门 (Quick Start)", "快速入门-quick-start"),
        ("Швидкий старт: встановлення", "швидкий-старт-встановлення"),
        ("クイックスタート — 概要", "クイックスタート--概要"),
    ],
)
def test_heading_anchor_unchanged_for_existing_locales(
    heading: str, anchor: str
) -> None:
    assert check_cross_references.heading_to_anchor(heading) == anchor


def test_in_page_link_keeping_zwnj_passes(
    repo: Path, capsys: pytest.CaptureFixture[str]
) -> None:
    (repo / "README.md").write_text(
        f"# {PERSIAN_HEADING}\n\n[link](#{PERSIAN_ANCHOR})\n", encoding="utf-8"
    )

    assert check_cross_references.main() == 0
    assert "broken anchor" not in capsys.readouterr().out


def test_in_page_link_missing_zwnj_is_reported(
    repo: Path, capsys: pytest.CaptureFixture[str]
) -> None:
    anchor_without_zwnj = PERSIAN_ANCHOR.replace(ZWNJ, "")
    (repo / "README.md").write_text(
        f"# {PERSIAN_HEADING}\n\n[link](#{anchor_without_zwnj})\n", encoding="utf-8"
    )

    assert check_cross_references.main() == 1
    assert "broken anchor" in capsys.readouterr().out