Kjell Tore Guttormsen
3233b19b30
The operator asked for a job that checks at least weekly whether Google OKF has moved, and messages the right repo immediately when it has. It belongs here rather than in `.claude` because knowing what a meaningful spec change IS requires owning the pin, the runbook and the always-latest policy. `tools/okf_watch.py`, stdlib only, driving git against the local read-only mirror. It lives outside `src/` so it never enters a wheel; a new packaging test holds that as a promise rather than an accident of the build config. Three properties carry the design, and each closes a failure this repo has actually met: 1. A failed call is never an empty result. Every git invocation raises on a non-zero exit and carries stderr, so a caller reading "" knows the query ran. The precedent is `grep ... | head; echo $?` reporting head's exit status - a broken query read as a quiet upstream. 2. It proves it can find, every run. Before believing any zero it re-runs the full detect-and-classify path over `ad30107^1..ad30107`, a range known to have changed SPEC.md. An empty known-positive aborts loudly rather than reporting a clean sweep. Network failure likewise raises; it never degrades to "no change". 3. It reports on change, not on state. A pin-keyed state file records what has been announced; moving the pin resets it, because a pin move means everything behind it was absorbed. Quiet is the enumerated list, not signal. Enumerating what counts as normative can only match what upstream has already invented, so anything new would fall outside it and the watch would go silent - failing in the direction nobody notices. A small measured quiet list, everything else reports. README.md is deliberately not quiet: the repository move was announced in a README commit. Sixteen tests build their own git repository in tmp_path rather than skipping when the mirror is absent - a skipped test preserves nothing on the machine where the dependency exists. All four load-bearing behaviours were mutation- tested red before this landed. Two more tests exist because building this fired a real false alarm: running with `--pin` and without `--dry-run` delivered two live coord messages. The override now implies dry-run, enforced in argument parsing rather than remembered, and `.claude` has the correction. The runbook gains a section stating what the watch CANNOT do, because that is the part a future session will otherwise assume away: it sees commits, not meaning. It would have fired on the 2026-08 tightening because SPEC.md changed, but no commit list says a value that conformed last month no longer does, and none says is_stale reversed. Its output is "run the runbook", never "here is your exposure".
64 lines
2.8 KiB
Python
64 lines
2.8 KiB
Python
"""Packaging contract: a PEP 561 typed package with exactly one dependency.
|
|
|
|
Consumers run mypy --strict against the inline annotations; without the
|
|
py.typed marker mypy degrades every imported symbol to Any.
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
from pathlib import Path
|
|
|
|
import pytest
|
|
|
|
import llm_ingestion_okf
|
|
|
|
PROJECT_ROOT = Path(__file__).resolve().parents[1]
|
|
|
|
|
|
def test_package_ships_py_typed_marker() -> None:
|
|
package_dir = Path(llm_ingestion_okf.__file__).parent
|
|
assert (package_dir / "py.typed").is_file()
|
|
|
|
|
|
def test_the_only_runtime_dependency_is_the_security_boundary() -> None:
|
|
"""The stdlib-only rule, enforced rather than asserted in prose.
|
|
|
|
One dependency is permitted — the guard — because security is the one
|
|
thing this library must not implement. Everything else stays stdlib, so
|
|
a consumer vendoring this package takes on no transitive surface. The
|
|
version RANGE is the pin: it resolves against a package index, and is
|
|
satisfied by the git+https tag install until that index exists.
|
|
"""
|
|
tomllib = pytest.importorskip("tomllib") # stdlib from 3.11; the pin holds on 3.10 too
|
|
pyproject = tomllib.loads((PROJECT_ROOT / "pyproject.toml").read_text(encoding="utf-8"))
|
|
assert pyproject["project"]["dependencies"] == ["llm-ingestion-guard>=0.3,<0.4"]
|
|
|
|
|
|
def test_the_declared_version_agrees_with_the_packaged_one() -> None:
|
|
"""The two places a version is written must not drift apart.
|
|
|
|
The install channel is a direct git reference, so a consumer pins a TAG
|
|
while pip records `project.version`. Nothing in the run path reads
|
|
`__version__` — which is exactly why a stale one survives a green suite,
|
|
and why a consumer installing at a pre-release tag can end up with a
|
|
package that reports the previous release. This is the only machine check
|
|
on that; the tag name itself remains a human step.
|
|
"""
|
|
tomllib = pytest.importorskip("tomllib")
|
|
pyproject = tomllib.loads((PROJECT_ROOT / "pyproject.toml").read_text(encoding="utf-8"))
|
|
assert llm_ingestion_okf.__version__ == pyproject["project"]["version"]
|
|
|
|
|
|
def test_operational_tooling_stays_out_of_the_wheel() -> None:
|
|
"""`tools/` is ours, not the consumer's.
|
|
|
|
The upstream watch drives git and the coord mailbox — machinery that is
|
|
meaningful on this machine and meaningless in a consumer's site-packages.
|
|
It lives outside `src/` so it cannot ship, and this test is what makes
|
|
that a promise instead of an accident of the current build config.
|
|
"""
|
|
tomllib = pytest.importorskip("tomllib")
|
|
pyproject = tomllib.loads((PROJECT_ROOT / "pyproject.toml").read_text(encoding="utf-8"))
|
|
packages = pyproject["tool"]["hatch"]["build"]["targets"]["wheel"]["packages"]
|
|
assert packages == ["src/llm_ingestion_okf"]
|
|
assert (PROJECT_ROOT / "tools" / "okf_watch.py").is_file(), "the test must have a subject"
|