First public release, published as one snapshot. What changed between versions is in CHANGELOG.md. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
1181 lines
57 KiB
Python
1181 lines
57 KiB
Python
"""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 <nonexistent>` 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"<html")}
|
|
with self.assertRaises(watch.WatchError):
|
|
self.check(answers)
|
|
|
|
def test_a_page_that_is_not_a_list_is_a_failure(self) -> 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)], '<https://example.invalid/x>; 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"] = "<x>; 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"], '<x>; 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 = '<Update label="1.0.0" description="May 1, 2026">\n * First tools\n</Update>\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'<h2 id="1-0-0">1.0.0</h2>')
|
|
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()
|