bitexoft-verify 0.2.0__py3-none-any.whl

bitexoft_verify/__init__.py

@@ -0,0 +1,3 @@
+"""bitexoft-verify: the platform's only definition of "correct"."""
+
+__version__ = "0.2.0"

bitexoft_verify/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

bitexoft_verify/checks/__init__.py

@@ -0,0 +1 @@
+"""Checks, one module per delivery."""

bitexoft_verify/checks/a1.py

@@ -0,0 +1,396 @@
+"""Delivery A1 — the domain: one instant of the match.
+
+What is checked is the *shape of the boundary*, never the implementation. How the
+Lyapunov maths or the centroid is written is the author's business; that an invalid
+position cannot come into existence is not.
+
+Two checks here are worth more than all the rest together:
+
+  * `boundary`   the domain imports no I/O. It is what keeps every later delivery cheap.
+  * `invariants` impossible objects are refused, with an error of the author's own.
+"""
+
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+
+from ..report import Check, Gate
+from .common import (
+    Context,
+    check_determinism,
+    check_domain_has_no_io,
+    check_manifest_keys,
+    check_symbol,
+    check_tests_cover_invariants,
+    check_tests_pass,
+    import_symbol,
+)
+
+PITCH_LENGTH_M = 105.0
+PITCH_WIDTH_M = 68.0
+
+
+def fixture(name: str) -> Path:
+    return Path(__file__).resolve().parent.parent / "data" / name
+
+
+def _domain(ctx: Context, reference: str):
+    return import_symbol(ctx.manifest.resolve(reference))
+
+
+def _position(ctx: Context):
+    return _domain(ctx, "<layers.domain>.models:Position")
+
+
+def _frame(ctx: Context):
+    return _domain(ctx, "<layers.domain>.models:Frame")
+
+
+def _domain_error(ctx: Context):
+    return _domain(ctx, "<layers.domain>.errors:DomainError")
+
+
+def check_position_rejects_impossible(ctx: Context) -> Check:
+    title = "Position refuses coordinates off the pitch"
+    try:
+        Position = _position(ctx)
+        DomainError = _domain_error(ctx)
+    except Exception as exc:  # noqa: BLE001
+        return Check("position_invariants", title, "skip", f"symbols not available yet: {exc}")
+
+    impossible = [
+        ("x=-3", {"x": -3.0, "y": 10.0}),
+        (f"x={PITCH_LENGTH_M + 50}", {"x": PITCH_LENGTH_M + 50, "y": 10.0}),
+        ("y=-1", {"x": 10.0, "y": -1.0}),
+        (f"y={PITCH_WIDTH_M + 20}", {"x": 10.0, "y": PITCH_WIDTH_M + 20}),
+    ]
+    accepted: list[str] = []
+    wrong_error: list[str] = []
+    for label, kwargs in impossible:
+        try:
+            Position(**kwargs)
+        except Exception as exc:  # noqa: BLE001
+            if not isinstance(exc, DomainError):
+                wrong_error.append(f"{label} raised {type(exc).__name__} instead of a DomainError")
+            continue
+        accepted.append(label)
+
+    problems = []
+    if accepted:
+        problems.append(f"accepted impossible positions: {', '.join(accepted)}")
+    if wrong_error:
+        problems.append("; ".join(wrong_error))
+
+    # The corners of the pitch are valid: an off-by-one here is a real bug.
+    for label, kwargs in [("0,0", {"x": 0.0, "y": 0.0}), ("105,68", {"x": PITCH_LENGTH_M, "y": PITCH_WIDTH_M})]:
+        try:
+            Position(**kwargs)
+        except Exception as exc:  # noqa: BLE001
+            problems.append(f"rejected the valid corner {label} ({type(exc).__name__})")
+
+    if problems:
+        return Check("position_invariants", title, "fail", " | ".join(problems))
+    return Check("position_invariants", title, "pass")
+
+
+def check_frame_rejects_impossible(ctx: Context) -> Check:
+    title = "Frame refuses impossible instants"
+    try:
+        Position = _position(ctx)
+        Frame = _frame(ctx)
+        DomainError = _domain_error(ctx)
+    except Exception as exc:  # noqa: BLE001
+        return Check("frame_invariants", title, "skip", f"symbols not available yet: {exc}")
+
+    players = (Position(x=10.0, y=10.0), Position(x=20.0, y=20.0))
+    ball = Position(x=52.5, y=34.0)
+    problems: list[str] = []
+
+    for label, kwargs in [
+        ("negative time", {"t": -1.0, "players": players, "ball": ball}),
+        ("a single player", {"t": 0.0, "players": (players[0],), "ball": ball}),
+        ("no players", {"t": 0.0, "players": (), "ball": ball}),
+    ]:
+        try:
+            Frame(**kwargs)
+        except Exception as exc:  # noqa: BLE001
+            if not isinstance(exc, DomainError):
+                problems.append(f"{label} raised {type(exc).__name__} instead of a DomainError")
+            continue
+        problems.append(f"accepted a frame with {label}")
+
+    if problems:
+        return Check("frame_invariants", title, "fail", " | ".join(problems))
+    return Check("frame_invariants", title, "pass")
+
+
+def check_value_semantics(ctx: Context) -> Check:
+    title = "Compared by value, hashable and immutable"
+    try:
+        Position = _position(ctx)
+        Frame = _frame(ctx)
+    except Exception as exc:  # noqa: BLE001
+        return Check("value_semantics", title, "skip", f"symbols not available yet: {exc}")
+
+    problems: list[str] = []
+    one, same, other = Position(x=10.0, y=20.0), Position(x=10.0, y=20.0), Position(x=11.0, y=20.0)
+
+    if one != same:
+        problems.append("two positions with the same coordinates are not equal")
+    if one == other:
+        problems.append("two different positions compare equal")
+    try:
+        if len({one, same, other}) != 2:
+            problems.append("hashing does not match equality")
+    except TypeError:
+        problems.append("Position is not hashable: it cannot go into a set or a dict key")
+
+    try:
+        object.__setattr__  # noqa: B018 - documents intent; the real attempt is below
+        one.x = 99.0  # type: ignore[misc]
+        problems.append("a position can be modified after construction")
+    except Exception:  # noqa: BLE001 - FrozenInstanceError or AttributeError, both fine
+        pass
+
+    players = (Position(x=10.0, y=10.0), Position(x=20.0, y=20.0))
+    ball = Position(x=52.5, y=34.0)
+    first, second = Frame(t=1.0, players=players, ball=ball), Frame(t=1.0, players=players, ball=ball)
+    if first != second:
+        problems.append("two frames with the same data are not equal")
+    try:
+        first.t = 5.0  # type: ignore[misc]
+        problems.append("a frame can be modified after construction")
+    except Exception:  # noqa: BLE001
+        pass
+
+    if problems:
+        return Check("value_semantics", title, "fail", " | ".join(problems))
+    return Check("value_semantics", title, "pass")
+
+
+def _square_frame(ctx: Context, half: float):
+    """A square centred on the pitch: centroid and spread are known without computing."""
+    Position = _position(ctx)
+    Frame = _frame(ctx)
+    cx, cy = PITCH_LENGTH_M / 2, PITCH_WIDTH_M / 2
+    corners = tuple(
+        Position(x=cx + dx * half, y=cy + dy * half) for dx, dy in ((-1, -1), (-1, 1), (1, -1), (1, 1))
+    )
+    return Frame(t=0.0, players=corners, ball=Position(x=cx, y=cy))
+
+
+def _line_frame(ctx: Context, step: float):
+    """Five players in a line through the centre.
+
+    A square cannot tell a mean apart from a maximum — every corner sits at the same
+    distance from the centre — so it would pass an implementation that returns the
+    furthest player instead of the average. This shape separates them: the mean
+    distance is 1.2 * step while the maximum is 2 * step.
+    """
+    Position = _position(ctx)
+    Frame = _frame(ctx)
+    cx, cy = PITCH_LENGTH_M / 2, PITCH_WIDTH_M / 2
+    players = tuple(Position(x=cx + offset * step, y=cy) for offset in (-2, -1, 0, 1, 2))
+    return Frame(t=0.0, players=players, ball=Position(x=cx, y=cy))
+
+
+def check_geometry(ctx: Context) -> Check:
+    title = "The centroid and the spread are right"
+    try:
+        square = _square_frame(ctx, half=10.0)
+        line = _line_frame(ctx, step=10.0)
+    except Exception as exc:  # noqa: BLE001
+        return Check("geometry", title, "skip", f"cannot build a frame yet: {exc}")
+
+    problems: list[str] = []
+    centre = getattr(square, "centroid", None)
+    if centre is None:
+        problems.append("Frame has no centroid")
+    elif abs(centre.x - PITCH_LENGTH_M / 2) > 1e-6 or abs(centre.y - PITCH_WIDTH_M / 2) > 1e-6:
+        problems.append(f"the centroid of a centred square is not the centre ({centre.x}, {centre.y})")
+
+    for frame, expected, shape in (
+        (square, (2 * 10.0**2) ** 0.5, "a square of half-side 10 m"),
+        (line, 12.0, "five players 10 m apart in a line"),
+    ):
+        try:
+            spread = frame.spread()
+        except Exception as exc:  # noqa: BLE001
+            problems.append(f"spread() raised {type(exc).__name__}: {exc}")
+            break
+        if abs(spread - expected) > 1e-6:
+            problems.append(
+                f"for {shape} the mean distance to the centroid is {expected:.4f} and spread() returned {spread}"
+            )
+
+    if problems:
+        return Check("geometry", title, "fail", " | ".join(problems))
+    return Check("geometry", title, "pass")
+
+
+def check_classification(ctx: Context) -> Check:
+    title = "Classification is monotonic and reaches all three states"
+    try:
+        BlockState = _domain(ctx, "<layers.domain>.models:BlockState")
+        Compactness = _domain(ctx, "<layers.domain>.analysis:BlockCompactness")
+        policy = Compactness()
+    except Exception as exc:  # noqa: BLE001
+        return Check("classification", title, "skip", f"symbols not available yet: {exc}")
+
+    order = {BlockState.COMPACT: 0, BlockState.STRETCHED: 1, BlockState.BROKEN: 2}
+    seen = []
+    problems: list[str] = []
+    for half in (2.0, 6.0, 10.0, 14.0, 18.0, 22.0, 26.0, 30.0):
+        try:
+            state = policy.classify(_square_frame(ctx, half=half))
+        except Exception as exc:  # noqa: BLE001
+            return Check("classification", title, "fail", f"classify() raised {type(exc).__name__}: {exc}")
+        if state not in order:
+            return Check("classification", title, "fail", f"classify() returned {state!r}, which is not a BlockState")
+        seen.append((half, state))
+
+    ranks = [order[state] for _, state in seen]
+    if ranks != sorted(ranks):
+        detail = ", ".join(f"{half:g}m->{state.name}" for half, state in seen)
+        problems.append(f"a tighter block is classified worse than a looser one: {detail}")
+    if len(set(ranks)) < 3:
+        problems.append(
+            "not all three states are reachable with the default thresholds: "
+            + ", ".join(f"{half:g}m->{state.name}" for half, state in seen)
+        )
+
+    if problems:
+        return Check("classification", title, "fail", " | ".join(problems))
+    return Check("classification", title, "pass")
+
+
+def check_thresholds_are_validated(ctx: Context) -> Check:
+    title = "BlockCompactness refuses thresholds that make no sense"
+    try:
+        Compactness = _domain(ctx, "<layers.domain>.analysis:BlockCompactness")
+    except Exception as exc:  # noqa: BLE001
+        return Check("thresholds", title, "skip", f"symbol not available yet: {exc}")
+    try:
+        Compactness(stretched_above=30.0, broken_above=20.0)
+    except Exception:  # noqa: BLE001 - any refusal is fine; the point is that it refuses
+        return Check("thresholds", title, "pass")
+    return Check(
+        "thresholds",
+        title,
+        "fail",
+        "it accepted stretched_above above broken_above: the policy would never return STRETCHED",
+    )
+
+
+def check_cli_analyses_fixture(ctx: Context) -> Check:
+    title = "The program analyses the sample file"
+    try:
+        result = ctx.cli(["analyze", str(fixture("a1_match_sample.csv"))], timeout=120)
+    except subprocess.TimeoutExpired:
+        return Check("cli_analyze", title, "fail", "it did not finish within 120s")
+    except Exception as exc:  # noqa: BLE001
+        return Check("cli_analyze", title, "fail", f"could not run the entry point: {exc}")
+    if result.returncode != 0:
+        tail = (result.stderr or result.stdout).strip().splitlines()[-3:]
+        return Check("cli_analyze", title, "fail", " / ".join(tail) or f"exit code {result.returncode}")
+    lines = [line for line in result.stdout.splitlines() if line.strip()]
+    if len(lines) < 10:
+        return Check("cli_analyze", title, "fail", f"it printed {len(lines)} lines: where is the table?")
+    states = {"COMPACT", "STRETCHED", "BROKEN", "compact", "stretched", "broken"}
+    if not any(state in result.stdout for state in states):
+        return Check("cli_analyze", title, "fail", "the output names no block state")
+    return Check("cli_analyze", title, "pass")
+
+
+def check_cli_fails_cleanly(ctx: Context) -> Check:
+    title = "With impossible data it fails cleanly, without a traceback"
+    try:
+        result = ctx.cli(["analyze", str(fixture("a1_impossible_sample.csv"))], timeout=120)
+    except subprocess.TimeoutExpired:
+        return Check("cli_bad_input", title, "fail", "it did not finish within 120s")
+    except Exception as exc:  # noqa: BLE001
+        return Check("cli_bad_input", title, "fail", f"could not run the entry point: {exc}")
+
+    if "Traceback (most recent call last)" in (result.stderr or ""):
+        return Check(
+            "cli_bad_input",
+            title,
+            "fail",
+            "it printed a traceback: catch your DomainError at the boundary and explain the problem",
+        )
+    if result.returncode == 0:
+        return Check("cli_bad_input", title, "fail", "it exited with 0 on data that cannot be valid")
+    if result.returncode != 2:
+        return Check(
+            "cli_bad_input",
+            title,
+            "fail",
+            f"it exited with {result.returncode}; the contract asks for 2 so a script can tell bad data from a crash",
+        )
+    if not (result.stderr or result.stdout).strip():
+        return Check("cli_bad_input", title, "fail", "it failed silently: say which row and why")
+    return Check("cli_bad_input", title, "pass")
+
+
+def gates(ctx: Context) -> list[Gate]:
+    acceptance = Gate(
+        "acceptance",
+        [
+            check_manifest_keys(ctx, ["project.id", "project.package", "layers.domain", "cli.module"]),
+            check_symbol(
+                ctx,
+                "<layers.domain>.models:Position",
+                shape="frozen-dataclass",
+                members=["x", "y", "distance_to"],
+                check_id="position",
+            ),
+            check_symbol(
+                ctx,
+                "<layers.domain>.models:Frame",
+                shape="frozen-dataclass",
+                members=["t", "players", "ball", "centroid", "spread"],
+                check_id="frame",
+            ),
+            check_symbol(
+                ctx,
+                "<layers.domain>.models:BlockState",
+                shape="enum",
+                members=["COMPACT", "STRETCHED", "BROKEN"],
+                check_id="block_state",
+            ),
+            check_symbol(ctx, "<layers.domain>.errors:DomainError", shape="exception", check_id="domain_error"),
+            check_symbol(
+                ctx, "<layers.domain>.analysis:BlockCompactness", members=["classify"], check_id="compactness"
+            ),
+            check_position_rejects_impossible(ctx),
+            check_frame_rejects_impossible(ctx),
+            check_value_semantics(ctx),
+            check_geometry(ctx),
+            check_classification(ctx),
+            check_thresholds_are_validated(ctx),
+            check_cli_analyses_fixture(ctx),
+            check_cli_fails_cleanly(ctx),
+            check_determinism(ctx, ["analyze", str(fixture("a1_match_sample.csv"))]),
+        ],
+    )
+    design = Gate(
+        "design",
+        [
+            check_domain_has_no_io(ctx),
+            check_tests_pass(ctx),
+            check_tests_cover_invariants(ctx, ["InvalidPosition", "InvalidFrame", "DomainError"]),
+        ],
+    )
+    evidence = Gate(
+        "evidence",
+        [
+            Check(
+                "written",
+                "Your written explanation",
+                "skip",
+                "this gate is yours to close on the platform: write the why and compare it against the rubric",
+            )
+        ],
+    )
+    return [acceptance, design, evidence]