fix: resolve catalog tooling review gaps

Author: xxg1413

.github/workflows/link-audit.yml

@@ -23,7 +23,7 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
         with:
-          python-version: "3.12"
+          python-version-file: ".python-version"
           cache: pip
 
       - name: Install Python dependencies

.github/workflows/validate.yml

@@ -24,7 +24,7 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
         with:
-          python-version: "3.12"
+          python-version-file: ".python-version"
           cache: pip
 
       - name: Install Python dependencies

.gitignore

@@ -45,6 +45,8 @@ temp/
 .tmp/
 
 # Python
+.venv/
+venv/
 __pycache__/
 *.pyc
 

CONTRIBUTING.md

@@ -49,12 +49,12 @@ it for review and provide repeatable evidence.
 
 ## Local setup
 
-Install Python 3.12, Ruby, Bundler, and the repository dependencies:
+Install the exact Python version from `.python-version`, Ruby, Bundler, and the
+repository dependencies:
 
 ```bash
 python -m venv .venv
 . .venv/bin/activate
-python -m pip install --upgrade pip
 python -m pip install -r requirements-dev.lock.txt
 bundle install
 ```

pyproject.toml

@@ -1,28 +1,3 @@
-[build-system]
-requires = ["setuptools==80.9.0"]
-build-backend = "setuptools.build_meta"
-
-[project]
-name = "flypython-catalog-tools"
-version = "0.1.0"
-description = "Validation and safe link checking for the FlyPython resource catalog"
-requires-python = ">=3.12,<3.13"
-dependencies = [
-  "PyYAML==6.0.3",
-  "requests==2.32.5",
-  "urllib3==2.6.3",
-]
-
-[project.optional-dependencies]
-dev = ["pytest==9.1.1"]
-
-[project.scripts]
-flypython-check-links = "tools.check_links:main"
-flypython-validate-catalog = "tools.validate_catalog:main"
-
-[tool.setuptools]
-packages = ["tools"]
-
 [tool.pytest.ini_options]
 addopts = "-q"
 testpaths = ["tests"]

tests/test_catalog.py

@@ -7,6 +7,7 @@
 
 from tools.catalog import (
     CatalogLoadError,
+    canonical_hostname,
     load_catalog,
     normalize_url,
     validate_catalog,
@@ -32,6 +33,13 @@ def test_loader_rejects_duplicate_yaml_keys(tmp_path) -> None:
         load_catalog(catalog)
 
 
+def test_loader_rejects_non_string_mapping_keys(tmp_path) -> None:
+    catalog = tmp_path / "resources.yml"
+    catalog.write_text("? [catalog]\n: {}\nresources: []\n", encoding="utf-8")
+    with pytest.raises(CatalogLoadError, match="mapping keys must be strings"):
+        load_catalog(catalog)
+
+
 def test_schema_duplicate_https_date_and_parity_errors(valid_catalog: dict) -> None:
     data = deepcopy(valid_catalog)
     data["resources"][0]["url"] = "http://example.invalid/docs"
@@ -71,6 +79,31 @@ def test_normalize_url_preserves_ipv6_brackets(url: str, expected: str) -> None:
     assert normalize_url(url) == expected
 
 
+def test_hostname_canonicalization_handles_idna_and_trailing_dot() -> None:
+    assert canonical_hostname("BÜCHER.example.") == "xn--bcher-kva.example"
+
+
+def test_validator_detects_idna_equivalent_duplicate_urls(valid_catalog: dict) -> None:
+    data = deepcopy(valid_catalog)
+    data["resources"][0]["url"] = "https://bücher.example/docs/"
+    data["resources"][1]["url"] = "https://xn--bcher-kva.example/docs"
+
+    codes = {
+        issue.code for issue in validate_catalog(data, today=date(2026, 8, 31))
+    }
+
+    assert "duplicate-url" in codes
+
+
+def test_validator_reports_non_string_mapping_keys(valid_catalog: dict) -> None:
+    data = deepcopy(valid_catalog)
+    data["catalog"][1] = "unexpected"
+
+    issues = validate_catalog(data, today=date(2026, 8, 31))
+
+    assert any(issue.code == "invalid-key" for issue in issues)
+
+
 def test_validator_exit_code_for_invalid_catalog(tmp_path) -> None:
     catalog = tmp_path / "resources.yml"
     catalog.write_text("catalog: {}\nresources: []\n", encoding="utf-8")

tests/test_check_links.py

@@ -170,7 +170,8 @@ def test_unsupported_redirect_status_is_fatal() -> None:
 
 @pytest.mark.parametrize("status_code", [403, 408, 425, 429, 500, 503])
 def test_transient_and_access_denied_statuses_need_review(status_code) -> None:
-    session = FakeSession(FakeResponse(status_code), FakeResponse(status_code))
+    head = FakeResponse(status_code)
+    session = FakeSession(head, FakeResponse(status_code))
     checker = LinkChecker(
         guard=guard_for(),
         session_factory=lambda: session,
@@ -179,6 +180,8 @@ def test_transient_and_access_denied_statuses_need_review(status_code) -> None:
         min_interval=0,
     )
     assert checker.check_one(link()).status == "review"
+    assert len(session.calls) == 1
+    assert head.closed is True
 
 
 @pytest.mark.parametrize(
@@ -345,6 +348,7 @@ def head(self, url, **kwargs):
         guard=guard_for(),
         session_factory=lambda: BrokenSession(FakeResponse(200)),
         workers=1,
+        retries=0,
         min_interval=0,
     )
     result = checker.check_one(link())
@@ -370,6 +374,7 @@ def head(self, url, **kwargs):
         guard=guard_for(),
         session_factory=lambda: BrokenSession(FakeResponse(200)),
         workers=1,
+        retries=0,
         min_interval=0,
     )
 
@@ -385,18 +390,22 @@ def head(self, url, **kwargs):
         guard=guard_for(),
         session_factory=lambda: SlowSession(FakeResponse(200)),
         workers=1,
+        retries=0,
         min_interval=0,
     )
 
     assert checker.check_one(link()).status == "review"
 
 
-def test_retry_configuration_ignores_unbounded_retry_after() -> None:
-    session = build_session(guard_for(), retries=2, backoff_factor=0.5)
+def test_adapter_transport_and_status_retries_are_disabled() -> None:
+    session = build_session(guard_for())
     try:
         retry = session.get_adapter("https://").max_retries
         assert retry.respect_retry_after_header is False
         assert retry.backoff_max == 5.0
+        assert retry.total == 0
+        assert retry.connect == 0
+        assert retry.read == 0
         assert retry.status == 0
         assert not retry.status_forcelist
     finally:
@@ -434,6 +443,108 @@ def head(self, url, **kwargs):
     assert second.closed is True
 
 
+@pytest.mark.parametrize("retry_after", ["60", "9" * 400])
+def test_large_retry_after_stops_without_get_fallback(
+    monkeypatch, retry_after: str
+) -> None:
+    response = FakeResponse(429, headers={"Retry-After": retry_after})
+    session = FakeSession(response)
+    checker = LinkChecker(
+        guard=guard_for(),
+        session_factory=lambda: session,
+        workers=1,
+        retries=2,
+        min_interval=0,
+    )
+    sleeps = []
+    monkeypatch.setattr(check_links.time, "sleep", sleeps.append)
+
+    result = checker.check_one(link())
+
+    assert result.status == "review"
+    assert len(session.calls) == 1
+    assert sleeps == []
+    assert response.closed is True
+
+
+def test_bounded_retry_after_is_honored(monkeypatch) -> None:
+    first = FakeResponse(429, headers={"Retry-After": "2"})
+    second = FakeResponse(200)
+
+    class RetrySession(FakeSession):
+        def __init__(self):
+            super().__init__(first)
+            self.responses = iter([first, second])
+
+        def head(self, url, **kwargs):
+            self.calls.append(("HEAD", url, kwargs))
+            return next(self.responses)
+
+    session = RetrySession()
+    checker = LinkChecker(
+        guard=guard_for(),
+        session_factory=lambda: session,
+        workers=1,
+        retries=1,
+        min_interval=0,
+    )
+    sleeps = []
+    monkeypatch.setattr(check_links.time, "sleep", sleeps.append)
+
+    result = checker.check_one(link())
+
+    assert result.status == "working"
+    assert len(session.calls) == 2
+    assert sleeps == [2.0]
+
+
+def test_transport_timeout_retry_is_manual() -> None:
+    response = FakeResponse(200)
+
+    class FlakySession(FakeSession):
+        def __init__(self):
+            super().__init__(response)
+            self.attempt = 0
+
+        def head(self, url, **kwargs):
+            self.calls.append(("HEAD", url, kwargs))
+            self.attempt += 1
+            if self.attempt == 1:
+                raise requests.Timeout("timed out")
+            return response
+
+    session = FlakySession()
+    checker = LinkChecker(
+        guard=guard_for(),
+        session_factory=lambda: session,
+        workers=1,
+        retries=1,
+        backoff_factor=0,
+        min_interval=0,
+    )
+
+    result = checker.check_one(link())
+
+    assert result.status == "working"
+    assert len(session.calls) == 2
+
+
+def test_wrapped_timeout_remains_review_needed() -> None:
+    class WrappedTimeoutSession(FakeSession):
+        def head(self, url, **kwargs):
+            raise requests.ConnectionError(TimeoutError("timed out"))
+
+    checker = LinkChecker(
+        guard=guard_for(),
+        session_factory=lambda: WrappedTimeoutSession(FakeResponse(200)),
+        workers=1,
+        retries=0,
+        min_interval=0,
+    )
+
+    assert checker.check_one(link()).status == "review"
+
+
 def test_responses_close_when_result_processing_fails(monkeypatch) -> None:
     head = FakeResponse(404)
     response = FakeResponse(200)

tools/catalog.py

@@ -55,6 +55,13 @@ def _construct_unique_mapping(
     mapping: dict[Any, Any] = {}
     for key_node, value_node in node.value:
         key = loader.construct_object(key_node, deep=deep)
+        if not isinstance(key, str):
+            raise ConstructorError(
+                "while constructing a mapping",
+                node.start_mark,
+                "mapping keys must be strings",
+                key_node.start_mark,
+            )
         if key in mapping:
             raise ConstructorError(
                 "while constructing a mapping",
@@ -97,9 +104,15 @@ def load_catalog(path: str | Path) -> dict[str, Any]:
     return value
 
 
+def canonical_hostname(value: str) -> str:
+    """Return the lowercase IDNA form used for URL equality and host buckets."""
+
+    return value.rstrip(".").encode("idna").decode("ascii").lower()
+
+
 def normalize_url(value: str) -> str:
     parsed = urlsplit(value.strip())
-    host = (parsed.hostname or "").lower()
+    host = canonical_hostname(parsed.hostname or "")
     port = parsed.port
     default_port = (parsed.scheme.lower() == "https" and port == 443) or (
         parsed.scheme.lower() == "http" and port == 80
@@ -131,9 +144,19 @@ def _missing_or_unknown(
     value: Mapping[str, Any], expected: set[str], location: str
 ) -> list[ValidationIssue]:
     issues: list[ValidationIssue] = []
-    for key in sorted(expected - set(value)):
+    string_keys = {key for key in value if isinstance(key, str)}
+    for key in value:
+        if not isinstance(key, str):
+            issues.append(
+                ValidationIssue(
+                    "invalid-key",
+                    f"{location}[{key!r}]",
+                    "mapping keys must be strings",
+                )
+            )
+    for key in sorted(expected - string_keys):
         issues.append(ValidationIssue("missing-field", location, f"missing {key!r}"))
-    for key in sorted(set(value) - expected):
+    for key in sorted(string_keys - expected):
         issues.append(
             ValidationIssue("unknown-field", f"{location}.{key}", "unknown field")
         )