"""Tests for tools/upstream_watch.py, the daily watch on the canonical Open Knowledge Format repository. The watch reports a NEGATIVE result almost every time it runs. That is the whole hazard: a run that never reached the network, or whose query silently matched nothing, produces the same "no change" as a run that genuinely found nothing. Trust in an absence that was never measured is worse than no watch, so every test here is about keeping those two outcomes distinguishable. The commit tests are ported from llm-ingestion-okf (tests/test_okf_watch.py, 3233b19) from pytest to unittest. The git-backed tests build their own repository in a temporary folder: pointing them at the real mirror would make the suite depend on upstream's history. No test reaches the network and no test sends a coord message. Run: python3 -m unittest discover -s tests -p 'test_upstream_watch.py' """ from __future__ import annotations import contextlib import hashlib import http.client import importlib.util import io import json import ssl import subprocess import sys import tempfile import unittest import unittest.mock import urllib.error from datetime import datetime, timezone from email.message import Message from pathlib import Path from typing import Any ROOT = Path(__file__).resolve().parents[1] _SPEC = importlib.util.spec_from_file_location("upstream_watch", ROOT / "tools" / "upstream_watch.py") assert _SPEC is not None and _SPEC.loader is not None watch = importlib.util.module_from_spec(_SPEC) sys.modules["upstream_watch"] = watch _SPEC.loader.exec_module(watch) def _git(repo: Path, *args: str) -> str: return subprocess.run(["git", *args], cwd=repo, capture_output=True, text=True, check=True).stdout def make_repo(parent: Path) -> Path: """A repository with one quiet commit and one normative commit.""" r = parent / "upstream" r.mkdir() _git(r, "init", "-q", "-b", "main") _git(r, "config", "user.email", "t@example.invalid") _git(r, "config", "user.name", "t") (r / "SPEC.md").write_text("Version 0.2\n", encoding="utf-8") (r / "CONTRIBUTING.md").write_text("hello\n", encoding="utf-8") _git(r, "add", "SPEC.md", "CONTRIBUTING.md") _git(r, "commit", "-q", "-m", "base") (r / "CONTRIBUTING.md").write_text("hello again\n", encoding="utf-8") _git(r, "add", "CONTRIBUTING.md") _git(r, "commit", "-q", "-m", "docs: contributing") (r / "SPEC.md").write_text("Version 0.2 tightened\n", encoding="utf-8") _git(r, "add", "SPEC.md") _git(r, "commit", "-q", "-m", "spec: tighten timestamps") return r class RepoTest(unittest.TestCase): def setUp(self) -> None: self._tmp = tempfile.TemporaryDirectory() self.tmp = Path(self._tmp.name) self.repo = make_repo(self.tmp) def tearDown(self) -> None: self._tmp.cleanup() # --- the exit-status / empty-result seam ----------------------------------------------------------------------------- class GitSeamTest(RepoTest): def test_a_failing_git_call_raises_instead_of_returning_empty(self) -> None: # `git log ` writes to stderr and exits non-zero. A helper that returned its empty stdout would # hand the caller "no commits": a negative manufactured by a broken query. with self.assertRaises(watch.WatchError) as ctx: watch.git(self.repo, "log", "--format=%H", "no-such-ref..HEAD") self.assertIn("exit", str(ctx.exception)) def test_an_empty_result_from_a_successful_call_is_not_an_error(self) -> None: # The other half of the seam: a real zero must still be readable as zero. head = watch.git(self.repo, "rev-parse", "HEAD") self.assertEqual(watch.git(self.repo, "log", "--format=%H", f"{head}..{head}"), "") # --- classification -------------------------------------------------------------------------------------------------- class ClassifyTest(unittest.TestCase): def test_a_spec_change_is_normative(self) -> None: normative, quiet = watch.classify(["SPEC.md", "CONTRIBUTING.md"]) self.assertEqual(normative, ["SPEC.md"]) self.assertEqual(quiet, ["CONTRIBUTING.md"]) def test_the_reference_reader_is_normative_because_is_stale_reversed_there(self) -> None: normative, _ = watch.classify(["src/reference_agent/bundle/document.py"]) self.assertEqual(normative, ["src/reference_agent/bundle/document.py"]) def test_the_viewer_is_quiet_but_the_readme_is_not(self) -> None: # README carries the relocation notice. That is how the move was announced. normative, quiet = watch.classify( ["src/reference_agent/viewer/static/viz.css", "bundles/acme_retail/viz.html", "README.md"] ) self.assertEqual(normative, ["README.md"]) self.assertEqual(quiet, ["src/reference_agent/viewer/static/viz.css", "bundles/acme_retail/viz.html"]) def test_an_unknown_path_defaults_to_normative(self) -> None: # Quiet is an enumerated list; signal is not. Over-firing is visible; under-firing is not. normative, quiet = watch.classify(["some/new/thing-upstream-adds-later.md"]) self.assertEqual(normative, ["some/new/thing-upstream-adds-later.md"]) self.assertEqual(quiet, []) # --- proving it can find --------------------------------------------------------------------------------------------- class ProveCanFindTest(RepoTest): def test_the_self_check_passes_on_a_range_that_really_changed_the_spec(self) -> None: base = watch.git(self.repo, "rev-parse", "HEAD~1") head = watch.git(self.repo, "rev-parse", "HEAD") watch.prove_can_find(self.repo, base, head) # must not raise def test_the_self_check_fails_loudly_when_the_query_finds_nothing(self) -> None: # An empty known-positive means the query is broken, not that upstream is quiet. head = watch.git(self.repo, "rev-parse", "HEAD") with self.assertRaises(watch.WatchError) as ctx: watch.prove_can_find(self.repo, head, head) self.assertIn("known-positive", str(ctx.exception)) def test_the_self_check_fails_loudly_when_the_range_is_unreachable(self) -> None: with self.assertRaises(watch.WatchError): watch.prove_can_find(self.repo, "deadbeef", "HEAD") # --- idempotence: report on change, not on state --------------------------------------------------------------------- class CommitStateTest(unittest.TestCase): def setUp(self) -> None: self._tmp = tempfile.TemporaryDirectory() self.path = Path(self._tmp.name) / "s.json" def tearDown(self) -> None: self._tmp.cleanup() def roundtrip(self, state: object) -> object: """Save the commits section and read the whole file back, as the next run would.""" assert isinstance(state, watch.CommitState) watch.save_state(self.path, {"commits": state.to_section()}) return watch.load_state(self.path).get("commits") def test_a_first_normative_change_is_reported(self) -> None: state = watch.CommitState.from_section(watch.load_state(self.path).get("commits"), pin="PIN") self.assertEqual(watch.decide(state, ["aaa", "bbb"]), ["aaa", "bbb"]) def test_the_same_upstream_state_is_not_reported_twice(self) -> None: state = watch.CommitState.from_section(None, pin="PIN") watch.decide(state, ["aaa"]) state.record(["aaa"]) again = watch.CommitState.from_section(self.roundtrip(state), pin="PIN") self.assertEqual(watch.decide(again, ["aaa"]), []) def test_only_the_new_commits_are_reported(self) -> None: # Upstream advancing must not re-announce what was already announced. state = watch.CommitState.from_section(None, pin="PIN") state.record(["aaa"]) later = watch.CommitState.from_section(self.roundtrip(state), pin="PIN") self.assertEqual(watch.decide(later, ["aaa", "bbb"]), ["bbb"]) def test_moving_our_pin_resets_what_counts_as_already_reported(self) -> None: # A pin move means we absorbed everything behind it. Nothing before it is news. state = watch.CommitState.from_section(None, pin="OLDPIN") state.record(["aaa"]) section = self.roundtrip(state) self.assertEqual(json.loads(self.path.read_text(encoding="utf-8"))["checks"]["commits"]["pin"], "OLDPIN") after = watch.CommitState.from_section(section, pin="NEWPIN") self.assertEqual(after.reported, []) # --- what gets sent -------------------------------------------------------------------------------------------------- class CommitBodyTest(unittest.TestCase): def test_the_coord_body_is_ascii_because_coord_send_requires_it(self) -> None: body = watch.render_body( pin="ad30107", head="beef123", commits=[("beef123", "spec: tighten timestamps")], normative=["SPEC.md"], quiet=["CONTRIBUTING.md"], ) body.encode("ascii") # raises UnicodeEncodeError if not def test_the_body_names_the_repository_it_watched(self) -> None: # "No change" is only meaningful with the object named. So is a hit. body = watch.render_body( pin="ad30107", head="beef123", commits=[("beef123", "x")], normative=["SPEC.md"], quiet=[] ) self.assertIn(watch.CANONICAL_REPO, body) self.assertIn("ad30107", body) self.assertIn("beef123", body) def test_the_body_carries_the_denominator_not_just_the_hits(self) -> None: body = watch.render_body( pin="p", head="h", commits=[("a", "one"), ("b", "two")], normative=["SPEC.md"], quiet=["CONTRIBUTING.md", "LICENSE.md"], ) self.assertIn("1 of 3", body) # --- the override that fired a false alarm --------------------------------------------------------------------------- class ArgsTest(unittest.TestCase): def test_an_overridden_pin_cannot_send_a_real_message(self) -> None: # Measured 2026-08-23 in the old watch: this exact combination delivered two false alarms. `--pin` exists so # the reporting branch can be exercised on demand against real upstream history; exercising it must never be # indistinguishable from upstream actually moving, so the override forces dry-run. with tempfile.TemporaryDirectory() as tmp: args = watch.parse_args(["--pin", "deadbeef", "--state", str(Path(tmp) / "s.json")]) self.assertTrue(args.dry_run) def test_the_real_pin_leaves_dry_run_alone(self) -> None: self.assertFalse(watch.parse_args([]).dry_run) # --- what moved with the watch --------------------------------------------------------------------------------------- class MovedTest(unittest.TestCase): def test_the_sender_is_this_repository(self) -> None: self.assertEqual(watch.SELF_REPO, "okf-wiki") def test_the_state_file_is_the_new_one_never_the_old_watchs(self) -> None: self.assertEqual(watch.DEFAULT_STATE, Path.home() / ".claude" / "okf-wiki-watch-state.json") def test_the_pin_stands_until_the_runbook_has_been_run(self) -> None: self.assertEqual(watch.PIN, "ad30107c31c06aec8a7d5636e0d1058118604e6f") # --- issues and pull requests, through GitHub's public API ----------------------------------------------------------- API = "https://api.github.com/repos/GoogleCloudPlatform/open-knowledge-format/issues" KNOWN_URL = API + "/8" T0 = "2026-09-01T10:00:00Z" T1 = "2026-09-02T10:00:00Z" T2 = "2026-09-03T10:00:00Z" def item(number: int, updated_at: str, pull: bool = False) -> dict[str, Any]: raw: dict[str, Any] = {"number": number, "updated_at": updated_at, "title": "Rye starter feeding schedule"} if pull: raw["pull_request"] = {"url": "x"} return raw def ok(data: object, link: str | None = None) -> tuple[int, dict[str, str], bytes]: headers = {"Link": link} if link else {} return 200, headers, json.dumps(data).encode("utf-8") def list_url(since: str | None = None) -> str: url = API + "?state=all&sort=updated&direction=desc&per_page=100" return url + "&since=" + since if since else url def probe_url(since: str) -> str: """The list asked from the known issue's own time, oldest first: the known issue must be on its first page.""" return API + "?state=all&sort=updated&direction=asc&per_page=10&since=" + since class FakeFetch: """Fixed, synthetic answers by URL. An unexpected URL fails the test: no test reaches the network.""" def __init__(self, answers: dict[str, tuple[int, dict[str, str], bytes]]) -> None: self.answers = answers self.calls: list[str] = [] def __call__(self, url: str) -> tuple[int, dict[str, str], bytes]: self.calls.append(url) if url not in self.answers: raise AssertionError(f"unexpected URL {url}") return self.answers[url] def issues_section(seen: dict[int, tuple[str, str]], since: str) -> dict[str, Any]: return {"seen": {str(n): {"kind": k, "updated_at": u} for n, (k, u) in seen.items()}, "since": since} class IssuesTest(unittest.TestCase): def ctx(self, fetch: FakeFetch) -> Any: return watch.Context(mirror=Path("/nonexistent"), pin=watch.PIN, no_fetch=True, fetch=fetch) def check(self, answers: dict[str, tuple[int, dict[str, str], bytes]], section: object = None) -> Any: return watch.check_issues(self.ctx(FakeFetch(answers)), section) def known(self) -> dict[str, tuple[int, dict[str, str], bytes]]: return {KNOWN_URL: ok(item(8, T0)), probe_url(T0): ok([item(8, T0), item(3, T1)])} # the known positive def test_the_known_issue_missing_fails_loudly(self) -> None: with self.assertRaises(watch.WatchError) as ctx: self.check({KNOWN_URL: (404, {}, b'{"message": "Not Found"}'), list_url(): ok([item(8, T0)])}) self.assertIn("known-positive", str(ctx.exception)) def test_an_answer_for_another_number_is_not_the_known_issue(self) -> None: with self.assertRaises(watch.WatchError) as ctx: self.check({KNOWN_URL: ok(item(9, T0)), list_url(): ok([item(8, T0)])}) self.assertIn("known-positive", str(ctx.exception)) def test_a_first_run_list_without_the_known_issue_fails(self) -> None: with self.assertRaises(watch.WatchError): self.check({**self.known(), list_url(): ok([item(1, T0)])}) def test_a_list_from_the_known_issues_own_time_without_it_fails_every_run(self) -> None: # The known issue rarely changes, so the list since the last run almost never holds it. The list is shown to # find by a second call every run: asked from #8's own time (the boundary is included, measured 08.10.2026). answers = {KNOWN_URL: ok(item(8, T0)), probe_url(T0): ok([item(3, T1)]), list_url(T1): ok([])} with self.assertRaises(watch.WatchError) as ctx: self.check(answers, issues_section({8: ("issue", T0)}, T1)) self.assertIn("known-positive", str(ctx.exception)) def test_an_empty_list_from_the_known_issues_own_time_fails(self) -> None: answers = {KNOWN_URL: ok(item(8, T0)), probe_url(T0): ok([]), list_url(T1): ok([])} with self.assertRaises(watch.WatchError): self.check(answers, issues_section({8: ("issue", T0)}, T1)) def test_the_list_is_read_newest_first(self) -> None: # Pages read oldest first can skip an item when another moves to the end mid-read; newest first can only # repeat one, and anything changed during the read is newer than `since` and comes next run. fetch = FakeFetch({**self.known(), list_url(T1): ok([])}) watch.check_issues(self.ctx(fetch), issues_section({8: ("issue", T0)}, T1)) self.assertTrue(any("direction=desc" in url and "since=" + T1 in url for url in fetch.calls)) # refusals and broken answers are never "nothing new" def test_a_403_on_the_list_is_a_failure_not_an_empty_result(self) -> None: with self.assertRaises(watch.WatchError) as ctx: self.check({**self.known(), list_url(): (403, {"X-RateLimit-Remaining": "0"}, b"{}")}) self.assertIn("403", str(ctx.exception)) def test_a_429_on_the_known_issue_is_a_failure(self) -> None: with self.assertRaises(watch.WatchError) as ctx: self.check({KNOWN_URL: (429, {}, b"{}"), list_url(): ok([item(8, T0)])}) self.assertIn("429", str(ctx.exception)) def test_a_broken_second_page_is_a_failure(self) -> None: page2 = list_url() + "&page=2" answers = {**self.known(), list_url(): ok([item(8, T0)], f'<{page2}>; rel="next"'), page2: (200, {}, b" None: with self.assertRaises(watch.WatchError): self.check({**self.known(), list_url(): ok({"message": "moved"})}) def test_an_item_without_a_time_is_a_failure(self) -> None: with self.assertRaises(watch.WatchError): self.check({**self.known(), list_url(): ok([item(8, T0), {"number": 2}])}) def test_a_next_link_off_the_api_is_refused(self) -> None: answers = {**self.known(), list_url(): ok([item(8, T0)], '; rel="next"')} with self.assertRaises(watch.WatchError): self.check(answers) def test_every_page_is_read_until_the_last(self) -> None: # The shape GitHub sends (measured 08.10.2026): the repository by id, and a cursor. page2 = "https://api.github.com/repositories/1234/issues?state=all&after=Y3Vyc29y&page=2" answers = { **self.known(), list_url(): ok([item(8, T0)], f'<{page2}>; rel="next", <{page2}>; rel="last"'), page2: ok([item(9, T1, pull=True)]), } result = self.check(answers) self.assertEqual(sorted(result.section["seen"]), ["8", "9"]) # first run def test_a_first_run_registers_everything_and_reports_nothing(self) -> None: answers = {**self.known(), list_url(): ok([item(8, T0), item(3, T1), item(5, T2, pull=True)])} result = self.check(answers) self.assertIn("first run: 2 issues and 1 pull requests registered", result.summary) self.assertEqual(result.report, "") self.assertEqual(result.section["since"], T2) self.assertEqual(result.section["seen"]["5"], {"kind": "pull request", "updated_at": T2}) # later runs def test_the_list_is_asked_for_what_changed_since_the_state(self) -> None: fetch = FakeFetch({**self.known(), list_url(T1): ok([])}) watch.check_issues(self.ctx(fetch), issues_section({8: ("issue", T0)}, T1)) self.assertIn(list_url(T1), fetch.calls) def test_a_new_issue_since_the_state_is_reported(self) -> None: answers = {**self.known(), list_url(T1): ok([item(31, T2)])} result = self.check(answers, issues_section({8: ("issue", T0)}, T1)) self.assertIn("new", result.report) self.assertIn("#31", result.report) self.assertIn(T2, result.report) self.assertIn("1 new and 0 changed", result.summary) def test_a_changed_issue_is_reported(self) -> None: answers = {**self.known(), list_url(T1): ok([item(12, T2, pull=True)])} result = self.check(answers, issues_section({8: ("issue", T0), 12: ("pull request", T1)}, T1)) self.assertIn("changed", result.report) self.assertIn("pull request", result.report) self.assertIn("#12", result.report) self.assertIn("0 new and 1 changed", result.summary) def test_an_unchanged_issue_is_silent(self) -> None: # The list is inclusive of `since`, so the newest item seen last time comes back unchanged every run. answers = {**self.known(), list_url(T1): ok([item(12, T1)])} result = self.check(answers, issues_section({8: ("issue", T0), 12: ("issue", T1)}, T1)) self.assertEqual(result.report, "") self.assertIn("so this zero is a measurement", result.summary) def test_the_state_keeps_what_it_saw_and_moves_since_to_the_newest_time(self) -> None: answers = {**self.known(), list_url(T0): ok([item(31, T2), item(12, T1)])} result = self.check(answers, issues_section({8: ("issue", T0), 12: ("issue", T0)}, T0)) self.assertEqual(result.section["since"], T2) self.assertEqual(sorted(result.section["seen"]), ["12", "31", "8"]) self.assertEqual(result.section["seen"]["12"]["updated_at"], T1) def test_the_issue_report_is_ascii_because_coord_send_requires_it(self) -> None: answers = {**self.known(), list_url(T1): ok([item(31, T2)])} result = self.check(answers, issues_section({8: ("issue", T0)}, T1)) result.report.encode("ascii") def test_a_malformed_issues_section_fails_instead_of_starting_over(self) -> None: with self.assertRaises(watch.WatchError): self.check({**self.known(), list_url(): ok([item(8, T0)])}, {"since": "yesterday", "seen": {}}) class HttpFetchTest(unittest.TestCase): def test_an_answer_comes_back_as_status_headers_and_body(self) -> None: class Answer: status = 200 headers = Message() def __enter__(self) -> Answer: self.headers["Link"] = "; rel=\"next\"" return self def __exit__(self, *exc: object) -> None: return None def read(self) -> bytes: return b"[]" status, headers, body = watch.http_fetch(KNOWN_URL, urlopen=lambda request, **kw: Answer()) self.assertEqual((status, body), (200, b"[]")) self.assertEqual(headers["Link"], '; rel="next"') def test_a_refusal_comes_back_as_its_status_for_the_caller_to_fail_on(self) -> None: def refuse(request: Any, **kw: Any) -> Any: raise urllib.error.HTTPError(request.full_url, 403, "rate limited", Message(), io.BytesIO(b"{}")) status, _, _ = watch.http_fetch(KNOWN_URL, urlopen=refuse) self.assertEqual(status, 403) def test_an_unreachable_network_is_loud(self) -> None: def unreachable(request: Any, **kw: Any) -> Any: raise urllib.error.URLError("no route to host") with self.assertRaises(watch.WatchError): watch.http_fetch(KNOWN_URL, urlopen=unreachable) def test_the_request_asks_for_the_api_format_and_sends_no_key(self) -> None: seen: list[Any] = [] def record(request: Any, **kw: Any) -> Any: seen.append(request) raise urllib.error.URLError("stop here") with self.assertRaises(watch.WatchError): watch.http_fetch(KNOWN_URL, urlopen=record) self.assertEqual(seen[0].get_header("Accept"), "application/vnd.github+json") self.assertIsNone(seen[0].get_header("Authorization")) def test_the_certificate_is_always_checked(self) -> None: # The python.org build on this machine ships with no CA certificates (measured 08.10.2026: 0 in its default # store), so the watch adds the system bundle; it never turns verification off to get an answer. contexts: list[Any] = [] def record(request: Any, **kw: Any) -> Any: contexts.append(kw.get("context")) raise urllib.error.URLError("stop here") with self.assertRaises(watch.WatchError): watch.http_fetch(KNOWN_URL, urlopen=record) self.assertEqual(contexts[0].verify_mode, ssl.CERT_REQUIRED) self.assertTrue(contexts[0].check_hostname) def test_a_system_bundle_that_cannot_be_loaded_is_loud(self) -> None: with tempfile.TemporaryDirectory() as tmp: bundle = Path(tmp) / "cert.pem" bundle.write_text("not a certificate\n", encoding="ascii") with self.assertRaises(watch.WatchError): watch.tls_context(bundle) def test_a_missing_system_bundle_leaves_the_default_store(self) -> None: context = watch.tls_context(Path("/nonexistent/cert.pem")) self.assertEqual(context.verify_mode, ssl.CERT_REQUIRED) # --- the commit check, end to end on a local repository -------------------------------------------------------------- class CommitsCheckTest(RepoTest): def setUp(self) -> None: super().setUp() _git(self.repo, "update-ref", "refs/remotes/origin/main", "HEAD") self.base = watch.git(self.repo, "rev-parse", "HEAD~2") self.positive = (watch.git(self.repo, "rev-parse", "HEAD~1"), watch.git(self.repo, "rev-parse", "HEAD")) def ctx(self, pin: str) -> Any: return watch.Context(mirror=self.repo, pin=pin, no_fetch=True, fetch=FakeFetch({}), known_positive=self.positive) def test_a_contract_bearing_commit_past_the_pin_is_reported(self) -> None: result = watch.check_commits(self.ctx(self.base), None) self.assertIn("spec: tighten timestamps", result.report) self.assertEqual(len(result.section["reported"]), 2) def test_what_was_reported_is_not_reported_again(self) -> None: first = watch.check_commits(self.ctx(self.base), None) again = watch.check_commits(self.ctx(self.base), first.section) self.assertEqual(again.report, "") self.assertIn("already announced", again.summary) def test_no_change_past_the_pin_is_a_measured_zero(self) -> None: head = watch.git(self.repo, "rev-parse", "HEAD") result = watch.check_commits(self.ctx(head), None) self.assertEqual(result.report, "") self.assertIn("this zero is a measurement", result.summary) def test_a_mirror_that_is_not_a_repository_fails(self) -> None: ctx = watch.Context(mirror=self.tmp / "nothing", pin=self.base, no_fetch=True, fetch=FakeFetch({})) with self.assertRaises(watch.WatchError): watch.check_commits(ctx, None) def test_an_upstream_subject_outside_ascii_still_gives_an_ascii_body(self) -> None: body = watch.render_body(pin="p", head="h", commits=[("a", "spec: na\u00efve d\u00e9j\u00e0")], normative=["SPEC.md"], quiet=[]) body.encode("ascii") # --- the run: a list of checks, all measured or nothing sent --------------------------------------------------------- class CoordScriptTest(unittest.TestCase): """The mailbox plugin moved marketplace (ktg-plugin-marketplace -> ktg-privat): the watch then failed every morning with "repo-mailbox plugin cache not found". The script is looked up under every marketplace.""" def make(self, home: Path, market: str, version: str) -> Path: script = home / ".claude" / "plugins" / "cache" / market / "repo-mailbox" / version / "scripts" / "coord-send.sh" script.parent.mkdir(parents=True) script.write_text("#!/bin/bash\n", encoding="utf-8") return script def test_the_newest_version_under_any_marketplace_is_used(self) -> None: with tempfile.TemporaryDirectory() as tmp: home = Path(tmp) self.make(home, "ktg-plugin-marketplace", "0.9.0") newest = self.make(home, "ktg-privat", "0.38.0") with unittest.mock.patch.object(Path, "home", return_value=home): self.assertEqual(watch._coord_send_script(), newest) def test_no_mailbox_anywhere_is_an_error_naming_the_cache(self) -> None: with tempfile.TemporaryDirectory() as tmp: (Path(tmp) / ".claude" / "plugins" / "cache" / "ktg-privat").mkdir(parents=True) with unittest.mock.patch.object(Path, "home", return_value=Path(tmp)): with self.assertRaises(watch.WatchError) as caught: watch._coord_send_script() self.assertIn("repo-mailbox", str(caught.exception)) class FakeSend: def __init__(self) -> None: self.sent: list[tuple[str, str, str, bool, bool]] = [] def __call__(self, to: str, subject: str, body: str, *, fyi: bool, dry_run: bool) -> None: self.sent.append((to, subject, body, fyi, dry_run)) def fixed(name: str, report: str = "", fail: bool = False) -> Any: def check(ctx: Any, section: object) -> Any: if fail: raise watch.WatchError("the bread did not rise") return watch.Result(summary=f"{name} measured", report=report, section={"runs": 1}) return check class RunTest(unittest.TestCase): def setUp(self) -> None: self._tmp = tempfile.TemporaryDirectory() self.state = Path(self._tmp.name) / "state.json" self.send = FakeSend() self.ctx = watch.Context(mirror=Path(self._tmp.name), pin=watch.PIN, no_fetch=True, fetch=FakeFetch({})) def tearDown(self) -> None: self._tmp.cleanup() def run_watch(self, checks: Any, dry_run: bool = False) -> tuple[int, str]: out = io.StringIO() with contextlib.redirect_stdout(out): code = watch.run(self.ctx, self.state, dry_run=dry_run, send=self.send, checks=checks) return code, out.getvalue() def test_the_checks_are_a_list_a_later_check_joins_by_name(self) -> None: self.assertEqual([name for name, _ in watch.CHECKS], ["commits", "issues", "home", "docs"]) def test_nothing_to_report_sends_nothing_and_writes_the_state(self) -> None: code, out = self.run_watch((("a", fixed("a")), ("b", fixed("b")))) self.assertEqual(code, 0) self.assertEqual(self.send.sent, []) self.assertIn("a measured", out) self.assertEqual(watch.load_state(self.state), {"a": {"runs": 1}, "b": {"runs": 1}}) def test_a_report_goes_to_this_repository_and_to_the_coordinator(self) -> None: self.run_watch((("a", fixed("a", report="rye #4\n")), ("b", fixed("b")))) self.assertEqual([(to, fyi) for to, _, _, fyi, _ in self.send.sent], [("okf-wiki", False), (".claude", True)]) self.assertIn("rye #4", self.send.sent[0][2]) self.assertIn("a", self.send.sent[0][1]) self.send.sent[0][2].encode("ascii") def test_the_message_names_its_sender_once(self) -> None: commits = watch.render_body(pin="p", head="h", commits=[("a", "one")], normative=["SPEC.md"], quiet=[]) self.run_watch((("commits", fixed("commits", report=commits)), ("b", fixed("b", report="rye #4\n")))) self.assertEqual(self.send.sent[0][2].count("Sent by tools/upstream_watch.py"), 1) def test_a_failed_send_writes_no_state(self) -> None: def refuse(to: str, subject: str, body: str, *, fyi: bool, dry_run: bool) -> None: raise watch.WatchError("coord-send failed") with self.assertRaises(watch.WatchError): watch.run(self.ctx, self.state, dry_run=False, send=refuse, checks=(("a", fixed("a", report="rye\n")),)) self.assertFalse(self.state.exists()) def test_a_dry_run_sends_as_dry_and_writes_no_state(self) -> None: _, out = self.run_watch((("a", fixed("a", report="rye #4\n")),), dry_run=True) self.assertTrue(all(dry for *_, dry in self.send.sent)) self.assertFalse(self.state.exists()) self.assertIn("dry run", out) def test_one_failed_check_fails_the_run_and_sends_nothing(self) -> None: checks = (("a", fixed("a", report="rye #4\n")), ("b", fixed("b", fail=True))) with self.assertRaises(watch.WatchError) as ctx: self.run_watch(checks) self.assertIn("b", str(ctx.exception)) self.assertEqual(self.send.sent, []) self.assertFalse(self.state.exists()) def test_sections_of_checks_not_run_are_kept(self) -> None: watch.save_state(self.state, {"later": {"x": 1}}) self.run_watch((("a", fixed("a")),)) self.assertEqual(watch.load_state(self.state), {"a": {"runs": 1}, "later": {"x": 1}}) def test_a_damaged_state_file_fails_before_any_check(self) -> None: self.state.write_text("{not json", encoding="utf-8") with self.assertRaises(watch.WatchError): self.run_watch((("a", fixed("a")),)) def test_an_empty_state_is_a_first_run_and_the_state_is_written(self) -> None: answers = {KNOWN_URL: ok(item(8, T0)), probe_url(T0): ok([item(8, T0)]), list_url(): ok([item(8, T0)])} self.ctx = watch.Context(mirror=Path(self._tmp.name), pin=watch.PIN, no_fetch=True, fetch=FakeFetch(answers)) _, out = self.run_watch((("issues", watch.check_issues),)) self.assertIn("first run: 1 issues and 0 pull requests registered", out) self.assertEqual(self.send.sent, []) self.assertEqual(watch.load_state(self.state)["issues"]["since"], T0) # the docs check fetches for minutes with hundreds of calls; it fails alone (order 8, point 6) def test_a_failed_docs_check_is_sent_even_when_nothing_else_is_news(self) -> None: # Exit 2 under the scheduler is seen by nobody; a docs check broken for weeks must not stay silent. code, _ = self.run_watch((("a", fixed("a")), ("docs", fixed("docs", fail=True)))) self.assertEqual(code, 2) self.assertEqual(len(self.send.sent), 2) self.assertIn("docs", self.send.sent[0][1]) self.assertIn("FAILED", self.send.sent[0][2]) def test_a_failed_docs_check_fails_alone_and_the_others_still_report(self) -> None: watch.save_state(self.state, {"docs": {"kept": 1}}) checks = (("a", fixed("a", report="rye #4\n")), ("docs", fixed("docs", fail=True))) code, out = self.run_watch(checks) self.assertEqual(code, 2) self.assertIn("docs: FAILED", out) self.assertIn("rye #4", self.send.sent[0][2]) self.assertIn("docs", self.send.sent[0][2]) self.assertEqual(watch.load_state(self.state), {"a": {"runs": 1}, "docs": {"kept": 1}}) def test_another_failed_check_still_fails_the_whole_run(self) -> None: checks = (("a", fixed("a", fail=True)), ("docs", fixed("docs", report="spade\n"))) with self.assertRaises(watch.WatchError): self.run_watch(checks) self.assertEqual(self.send.sent, []) self.assertFalse(self.state.exists()) def test_a_message_file_takes_the_message_and_the_state_is_written(self) -> None: # The trial runs of order 8 write the message to a file instead of sending it, and still keep their state, # so the second run can show that it reports nothing new. --dry-run writes no state, so it cannot show that. message = Path(self._tmp.name) / "message.txt" code = watch.run(self.ctx, self.state, dry_run=False, send=watch.file_send(message), checks=(("a", fixed("a", report="rye #4\n")),)) self.assertEqual(code, 0) text = message.read_text(encoding="utf-8") self.assertIn("rye #4", text) self.assertIn("to: okf-wiki", text) self.assertEqual(watch.load_state(self.state), {"a": {"runs": 1}}) def test_the_checks_can_be_chosen_by_name_and_the_rest_keep_their_state(self) -> None: args = watch.parse_args(["--check", "docs", "--state", str(self.state)]) self.assertEqual([name for name, _ in watch.chosen(args.check)], ["docs"]) self.assertEqual([name for name, _ in watch.chosen(None)], ["commits", "issues", "home", "docs"]) with self.assertRaises(SystemExit), contextlib.redirect_stderr(io.StringIO()): watch.parse_args(["--check", "bread"]) class RunbookTest(unittest.TestCase): def test_the_commit_message_points_at_this_repositorys_runbook(self) -> None: body = watch.render_body(pin="p", head="h", commits=[("a", "one")], normative=["SPEC.md"], quiet=[]) self.assertIn("docs/upstream-runbook.md", body) self.assertNotIn("llm-ingestion-okf", body) self.assertTrue((ROOT / "docs" / "upstream-runbook.md").is_file()) # --- the docs check: fetch, freeze, diff against the frozen copy, report only what is new ---------------------------- fetch_docs: Any = getattr(watch, "fetch_docs", None) # None until the docs check exists sys.path.insert(0, str(ROOT)) from okfwiki import sources # noqa: E402 D_BASE = "https://example.org/docs/en/" D_INDEX = "https://example.org/docs/llms.txt" D_CHANGELOG = D_BASE + "changelog.md" D_CHANGELOG_PAGE = D_BASE + "changelog" D_PREAMBLE = "> ## Garden Index\n> Fetch the garden index first.\n> Use it to find pages.\n\n" D_PREAMBLE_SPEC = {"lines": 3, "sha256": hashlib.sha256(D_PREAMBLE.rstrip("\n").encode()).hexdigest()} D_MD = "text/markdown; charset=utf-8" D_BLOCK = '\n * First tools\n\n' D_PAGES = {"soil.md": "# Soil\n\nCompost feeds the soil.\n", "tools/spade.md": "# Spade\n\nDig before the frost.\n"} DAY0 = datetime(2026, 10, 8, 5, 15, tzinfo=timezone.utc) DAY1 = datetime(2026, 10, 9, 5, 15, tzinfo=timezone.utc) DAY2 = datetime(2026, 10, 10, 5, 15, tzinfo=timezone.utc) DAY3 = datetime(2026, 10, 11, 5, 15, tzinfo=timezone.utc) class Site: """A synthetic garden site in the shape the fetcher reads; counts its calls. An unknown URL fails the test.""" def __init__(self, pages: dict[str, str], fail: str = "") -> None: self.pages = pages self.fail = fail self.calls = 0 def __call__(self, url: str) -> Any: self.calls += 1 if self.fail == "network": raise urllib.error.URLError("no route to the garden") if url == D_INDEX: if self.fail == "index": return fetch_docs.Fetched(500, url, "text/plain", b"") lines = [f"- [{rel}]({D_BASE}{rel}): A page." for rel in [*sorted(self.pages), "changelog.md"]] return fetch_docs.Fetched(200, url, "text/plain", ("# Garden\n\n## Pages\n\n" + "\n".join(lines) + "\n") .encode()) if url == D_CHANGELOG: return fetch_docs.Fetched(200, url, D_MD, (D_PREAMBLE + "# Changelog\n\n" + D_BLOCK).encode()) if url == D_CHANGELOG_PAGE: return fetch_docs.Fetched(200, url, "text/html", b'

1.0.0

') rel = url[len(D_BASE):] if url.startswith(D_BASE) and rel in self.pages: pre = "" if self.fail == "preamble" else D_PREAMBLE return fetch_docs.Fetched(200, url, D_MD, (pre + self.pages[rel]).encode()) raise AssertionError(f"unexpected URL {url}") class DocsCheckTest(unittest.TestCase): def setUp(self) -> None: self._tmp = tempfile.TemporaryDirectory() self.tmp = Path(self._tmp.name) self.preamble = self.tmp / "innledning.json" self.preamble.write_text(json.dumps(D_PREAMBLE_SPEC), encoding="utf-8") self.daily = self.tmp / "daglig" self.frozen = self.tmp / "20261008" self.config(Site(D_PAGES), DAY0) root, _ = watch.fetch_root(self.cfg, self.tmp / "work0", "2026-10-08T05:15:00Z") root.rename(self.frozen) self.assertEqual(sources.check(self.frozen), []) def tearDown(self) -> None: self._tmp.cleanup() def config(self, site: Site, when: datetime, **over: Any) -> None: self.site = site settings: dict[str, Any] = dict(enabled=True, daily=self.daily, frozen=self.frozen, preamble=self.preamble, base=D_BASE, index_url=D_INDEX, changelog=D_CHANGELOG, changelog_page=D_CHANGELOG_PAGE, pause=0.0, fetcher=site, clock=lambda: when) settings.update(over) self.cfg = watch.DocsConfig(**settings) def check(self, section: object = None) -> Any: ctx = watch.Context(mirror=Path("/nonexistent"), pin=watch.PIN, no_fetch=True, fetch=FakeFetch({}), docs=self.cfg) return watch.check_docs(ctx, section) def changed_site(self) -> Site: """Spade changed, soil gone, rake new.""" return Site({"tools/spade.md": "# Spade\n\nDig after the frost.\n", "tools/rake.md": "# Rake\n\nRake leaves.\n"}) # off by default def test_off_by_default_nothing_is_fetched_and_the_log_says_so(self) -> None: self.assertFalse(watch.docs_config({}).enabled) self.assertFalse(watch.DocsConfig().enabled) self.config(Site(D_PAGES, fail="network"), DAY1, enabled=False, setting="") result = self.check() self.assertEqual((result.report, self.site.calls), ("", 0)) self.assertIn("off", result.summary) self.assertFalse(self.daily.exists()) def test_only_the_word_on_turns_it_on(self) -> None: self.assertTrue(watch.docs_config({"OKF_WIKI_DOCS_CHECK": "on"}).enabled) cfg = watch.docs_config({"OKF_WIKI_DOCS_CHECK": "yes"}) self.assertFalse(cfg.enabled) self.config(Site(D_PAGES), DAY1, enabled=False, setting=cfg.setting) self.assertIn("'yes'", self.check().summary) def test_the_settings_and_their_defaults(self) -> None: cfg = watch.docs_config({}) self.assertEqual(cfg.daily, Path.home() / "okf" / "benk" / "samling1" / "daglig") self.assertEqual(cfg.frozen, Path.home() / "okf" / "benk" / "samling1" / "20261008") self.assertEqual((cfg.keep, cfg.bundle), (7, None)) cfg = watch.docs_config({"OKF_WIKI_DOCS_CHECK": "on", "OKF_WIKI_DOCS_DAILY": "/a", "OKF_WIKI_DOCS_FROZEN": "/b", "OKF_WIKI_DOCS_KEEP": "3", "OKF_WIKI_DOCS_BUNDLE": "/c", "OKF_WIKI_DOCS_PREAMBLE": "/d"}) self.assertEqual((cfg.daily, cfg.frozen, cfg.keep, cfg.bundle, cfg.preamble), (Path("/a"), Path("/b"), 3, Path("/c"), Path("/d"))) with self.assertRaises(watch.WatchError): watch.docs_config({"OKF_WIKI_DOCS_KEEP": "0", "OKF_WIKI_DOCS_CHECK": "on"}) # off, a bad setting of the check must not change the job: it is not read self.assertFalse(watch.docs_config({"OKF_WIKI_DOCS_KEEP": "0"}).enabled) # on: a dated K1 root and a diff against the frozen copy def test_on_it_fetches_into_a_dated_folder_that_passes_the_k1_check(self) -> None: self.config(self.changed_site(), DAY1) self.check() day = self.daily / "20261009" self.assertEqual(sources.check(day), []) self.assertEqual((day / "diff.json").read_text(encoding="utf-8"), sources.dump(sources.diff(self.frozen, day))) self.assertEqual([p.name for p in self.daily.iterdir()], ["20261009"]) def test_on_it_reports_new_changed_and_gone_against_the_frozen_copy(self) -> None: self.config(self.changed_site(), DAY1) result = self.check() for text in ("1 new", "1 changed", "1 gone", "kilde/docs-en-tools-rake.md", "kilde/docs-en-tools-spade.md", "kilde/docs-en-soil.md"): self.assertIn(text, result.report) result.report.encode("ascii") self.assertEqual(self.site.calls, 5) def test_no_difference_on_a_first_run_reports_nothing(self) -> None: self.config(Site(D_PAGES), DAY1) result = self.check() self.assertEqual(result.report, "") self.assertIn("0 new, 0 changed, 0 gone", result.summary) def test_the_same_differences_are_not_reported_twice(self) -> None: self.config(self.changed_site(), DAY1) first = self.check() self.config(self.changed_site(), DAY2) again = self.check(first.section) self.assertEqual(again.report, "") self.assertIn("nothing new since the last message", again.summary) self.assertEqual(again.section["diff_sha256"], first.section["diff_sha256"]) def test_only_what_is_new_since_the_last_message_is_reported(self) -> None: self.config(self.changed_site(), DAY1) first = self.check() site = self.changed_site() site.pages["tools/hoe.md"] = "# Hoe\n\nHoe the rows.\n" self.config(site, DAY2) later = self.check(first.section) self.assertIn("kilde/docs-en-tools-hoe.md", later.report) self.assertNotIn("kilde/docs-en-tools-rake.md", later.report) self.assertIn("2 new, 1 changed, 1 gone", later.report) def test_a_difference_that_goes_away_is_reported_once(self) -> None: self.config(self.changed_site(), DAY1) first = self.check() self.config(Site(D_PAGES), DAY2) back = self.check(first.section) self.assertIn("no longer differs", back.report) self.config(Site(D_PAGES), DAY3) self.assertEqual(self.check(back.section).report, "") def test_a_malformed_section_fails_instead_of_starting_over(self) -> None: self.config(self.changed_site(), DAY1) with self.assertRaises(watch.WatchError): self.check({"diff_sha256": 3}) def test_a_second_fetch_the_same_day_replaces_that_days_folder(self) -> None: self.config(Site(D_PAGES), DAY1) self.check() self.config(self.changed_site(), DAY1) self.check() day = self.daily / "20261009" self.assertEqual(sources.check(day), []) self.assertTrue((day / "kilde" / "docs-en-tools-rake.md").is_file()) self.assertEqual([p.name for p in self.daily.iterdir()], ["20261009"]) # retention: the last seven fetches, never the frozen copy, never anything else def test_the_oldest_fetches_beyond_the_limit_are_removed_and_nothing_else(self) -> None: self.daily.mkdir() for d in range(1, 9): (self.daily / f"2026100{d}").mkdir() (self.daily / "notes").mkdir() (self.daily / "20261001.txt").write_text("rye\n", encoding="utf-8") self.config(self.changed_site(), DAY1, keep=7) self.check() left = sorted(p.name for p in self.daily.iterdir()) self.assertEqual(left, ["20261001.txt", "20261003", "20261004", "20261005", "20261006", "20261007", "20261008", "20261009", "notes"]) def test_the_frozen_copy_is_never_removed_even_among_the_fetches(self) -> None: self.daily.mkdir() inside = self.daily / "20261001" self.frozen.rename(inside) self.frozen = inside for d in range(2, 9): (self.daily / f"2026100{d}").mkdir() self.config(self.changed_site(), DAY1, keep=2) self.check() self.assertEqual(sorted(p.name for p in self.daily.iterdir()), ["20261001", "20261008", "20261009"]) self.assertEqual(sources.check(inside), []) # a built collection gets its marks def test_with_a_built_collection_the_pages_on_changed_sources_are_marked(self) -> None: wiki = self.tmp / "wiki" wiki.mkdir() (wiki / "spade.md").write_text("---\ntype: Concept\nsources:\n - id: s-1\n resource: " "/kilde/docs-en-tools-spade.md\n---\n\n# Spade\n", encoding="utf-8") (wiki / "rye.md").write_text("---\ntype: Concept\n---\n\n# Rye\n", encoding="utf-8") self.config(self.changed_site(), DAY1, bundle=wiki) result = self.check() marks = json.loads((self.daily / "20261009" / "marks.json").read_text(encoding="utf-8")) self.assertEqual([p["page"] for p in marks["pages"]], ["spade.md"]) self.assertIn("1 page(s) marked", result.report) def test_the_message_says_the_update_is_a_build_in_a_session_from_the_fetch(self) -> None: # C19 (operator 07.11.2026): fetch, compare, mark and warn run unattended; the rebuild runs in a session self.config(self.changed_site(), DAY1) report = self.check().report self.assertNotIn("first delivery after v1", report) self.assertIn(f"To update, build from {self.daily / '20261009'} in a session with the okf-wiki skill", report) self.assertIn("no tool calls a model", report) # a failed fetch is a failure, and it leaves no half folder def test_a_failed_fetch_fails_the_check_and_leaves_no_folder(self) -> None: for fail in ("network", "index", "preamble"): with self.subTest(fail=fail): self.config(Site(D_PAGES, fail=fail), DAY1) with self.assertRaises(watch.WatchError): self.check() self.assertEqual(list(self.daily.iterdir()) if self.daily.exists() else [], []) def test_any_error_in_the_fetch_is_a_watch_error_so_docs_fails_alone(self) -> None: # A connection dropped mid-body raises http.client.IncompleteRead, which is not an OSError (review, order 8). class Dropped(Site): def __call__(self, url: str) -> Any: if url.endswith("spade.md"): raise http.client.IncompleteRead(b"Dig", 20) return super().__call__(url) self.config(Dropped(D_PAGES), DAY1) with self.assertRaises(watch.WatchError): self.check() self.assertEqual([p.name for p in self.daily.iterdir()], []) def test_a_daily_folder_that_is_a_file_is_a_watch_error(self) -> None: self.daily.write_text("rye\n", encoding="utf-8") self.config(self.changed_site(), DAY1) with self.assertRaises(watch.WatchError): self.check() def test_todays_folder_is_never_the_frozen_copy(self) -> None: self.daily.mkdir() inside = self.daily / "20261009" self.frozen.rename(inside) self.frozen = inside self.config(self.changed_site(), DAY1) with self.assertRaises(watch.WatchError): self.check() self.assertEqual(sources.check(inside), []) def test_a_frozen_copy_inside_a_dated_folder_is_never_removed(self) -> None: self.daily.mkdir() holder = self.daily / "20261001" holder.mkdir() self.frozen.rename(holder / "copy") self.frozen = holder / "copy" for d in range(2, 9): (self.daily / f"2026100{d}").mkdir() self.config(self.changed_site(), DAY1, keep=2) self.check() self.assertEqual(sources.check(holder / "copy"), []) def test_the_work_folders_of_a_killed_run_are_removed(self) -> None: self.daily.mkdir() (self.daily / ".20261008-abc123").mkdir() (self.daily / ".hidden").mkdir() self.config(self.changed_site(), DAY1) self.check() self.assertEqual(sorted(p.name for p in self.daily.iterdir()), [".hidden", "20261009"]) def test_the_folder_is_named_by_the_local_day(self) -> None: # 23:30 UTC on 8 October is already 9 October in Oslo in summer; the job's day is the operator's day. late = datetime(2026, 10, 8, 23, 30, tzinfo=timezone.utc) self.config(self.changed_site(), late) self.check() self.assertEqual([p.name for p in self.daily.iterdir()], [late.astimezone().strftime("%Y%m%d")]) def test_off_the_whole_run_writes_one_line_and_an_empty_section(self) -> None: state = self.tmp / "state.json" ctx = watch.Context(mirror=Path("/nonexistent"), pin=watch.PIN, no_fetch=True, fetch=FakeFetch({}), docs=watch.DocsConfig()) out = io.StringIO() with contextlib.redirect_stdout(out): code = watch.run(ctx, state, dry_run=False, send=FakeSend(), checks=watch.chosen(["docs"])) self.assertEqual(code, 0) self.assertEqual(out.getvalue().count("\n"), 1) self.assertIn("docs: off", out.getvalue()) self.assertEqual(watch.load_state(state), {"docs": {}}) def test_a_frozen_copy_that_fails_the_k1_check_fails(self) -> None: (self.frozen / "kilde" / "docs-en-soil.md").chmod(0o644) (self.frozen / "kilde" / "docs-en-soil.md").write_text("# Soil\n\nSand.\n", encoding="utf-8") self.config(self.changed_site(), DAY1) with self.assertRaises(watch.WatchError): self.check() # --- the home check: the announced new home (upstream PR #63, read 08.11.2026) ----------------------------------------- ORG_URL = "https://api.github.com/orgs/open-knowledge-format" ORG_REPOS_URL = ORG_URL + "/repos?type=public&per_page=100" PR_URL = "https://api.github.com/repos/GoogleCloudPlatform/open-knowledge-format/pulls/63" CANON_URL = "https://api.github.com/repos/GoogleCloudPlatform/open-knowledge-format" def org(public_repos: int, login: str = "open-knowledge-format") -> tuple[int, dict[str, str], bytes]: return ok({"login": login, "public_repos": public_repos, "type": "Organization"}) def repo(name: str, archived: bool = False) -> dict[str, Any]: return {"full_name": name, "html_url": f"https://github.com/{name}", "archived": archived} def pull(state: str = "open", merged: bool = False, number: int = 63) -> tuple[int, dict[str, str], bytes]: return ok({"number": number, "state": state, "merged": merged, "title": "Mark the repository as deprecated"}) def home(repos: list[str] | None = None, pr: tuple[int, dict[str, str], bytes] | None = None, archived: bool = False) -> dict[str, tuple[int, dict[str, str], bytes]]: """The four answers as measured on 08.11.2026 (0 public repos, #63 open, canonical not archived), unless told.""" names = repos or [] return { ORG_URL: org(len(names)), ORG_REPOS_URL: ok([repo(n) for n in names]), PR_URL: pr or pull(), CANON_URL: ok(repo("GoogleCloudPlatform/open-knowledge-format", archived=archived)), } class HomeTest(unittest.TestCase): """The move announced in #63 must not pass silently: the watch reads the new home's organisation every run.""" def check(self, answers: dict[str, tuple[int, dict[str, str], bytes]], section: object = None) -> Any: ctx = watch.Context(mirror=Path("/nonexistent"), pin=watch.PIN, no_fetch=True, fetch=FakeFetch(answers)) return watch.check_home(ctx, section) def test_the_state_measured_on_08_11_is_silent_on_a_first_run(self) -> None: result = self.check(home()) self.assertEqual(result.report, "") self.assertIn("0 public repositories", result.summary) self.assertIn("#63 open", result.summary) self.assertEqual(result.section, {"archived": False, "pr": "open", "repos": []}) def test_a_public_repository_in_the_new_home_is_reported_with_its_address(self) -> None: result = self.check(home(["open-knowledge-format/open-knowledge-format"])) self.assertIn("open-knowledge-format/open-knowledge-format", result.report) self.assertIn("https://github.com/open-knowledge-format/open-knowledge-format", result.report) self.assertIn("runbook", result.report) result.report.encode("ascii") def test_what_was_reported_is_not_reported_again(self) -> None: first = self.check(home(["open-knowledge-format/open-knowledge-format"])) again = self.check(home(["open-knowledge-format/open-knowledge-format"]), first.section) self.assertEqual(again.report, "") def test_a_second_repository_is_reported_alone(self) -> None: first = self.check(home(["open-knowledge-format/open-knowledge-format"])) names = ["open-knowledge-format/open-knowledge-format", "open-knowledge-format/viewer"] later = self.check(home(names), first.section) self.assertIn("open-knowledge-format/viewer", later.report) self.assertNotIn("new open-knowledge-format/open-knowledge-format", later.report) def test_the_deprecation_merged_is_reported(self) -> None: result = self.check(home(pr=pull(state="closed", merged=True)), {"archived": False, "pr": "open", "repos": []}) self.assertIn("#63", result.report) self.assertIn("merged", result.report) self.assertEqual(result.section["pr"], "merged") def test_the_deprecation_closed_unmerged_is_reported(self) -> None: result = self.check(home(pr=pull(state="closed"))) self.assertIn("closed without merge", result.report) def test_canonical_archived_is_reported(self) -> None: result = self.check(home(archived=True)) self.assertIn("archived", result.report) self.assertTrue(result.section["archived"]) def test_a_repository_gone_from_the_new_home_is_reported(self) -> None: before = {"archived": False, "pr": "open", "repos": ["open-knowledge-format/open-knowledge-format"]} result = self.check(home(), before) self.assertIn("gone", result.report) # a failed call is never an empty home def test_the_organisation_answering_404_fails_loudly(self) -> None: with self.assertRaises(watch.WatchError) as ctx: self.check({**home(), ORG_URL: (404, {}, b'{"message": "Not Found"}')}) self.assertIn("not 'nothing new'", str(ctx.exception)) def test_an_answer_for_another_organisation_fails(self) -> None: with self.assertRaises(watch.WatchError): self.check({**home(), ORG_URL: org(0, login="someone-else")}) def test_a_list_that_disagrees_with_the_count_fails(self) -> None: # The organisation has no public repository yet, so the list cannot be shown to find one; the count the # organisation gives of itself is the check that the list is whole. with self.assertRaises(watch.WatchError) as ctx: self.check({**home(), ORG_URL: org(1)}) self.assertIn("count", str(ctx.exception)) def test_a_403_on_the_repository_list_fails(self) -> None: with self.assertRaises(watch.WatchError): self.check({**home(), ORG_REPOS_URL: (403, {"x-ratelimit-remaining": "0"}, b"{}")}) def test_an_answer_for_another_pull_request_fails(self) -> None: with self.assertRaises(watch.WatchError): self.check(home(pr=pull(number=64))) def test_canonical_answering_404_fails(self) -> None: with self.assertRaises(watch.WatchError): self.check({**home(), CANON_URL: (404, {}, b"{}")}) def test_a_malformed_section_fails_instead_of_starting_over(self) -> None: with self.assertRaises(watch.WatchError): self.check(home(), {"pr": "open"}) if __name__ == "__main__": unittest.main()