feat: gate that every claim about podman is measured against podman

Rule two rested on statements no test ran. `compose2pod/podman.py` now holds
every claim the tool makes about podman's behaviour, and a refusal citing
podman draws its clause from there, so the claims can be enumerated rather
than grepped for.

The gate pairs each (site, claim) in the source with the row that measures
it, in both directions: a new podman-citing refusal without a row goes red,
and so does a row whose site or claim no longer exists.

Closes #109

Author: lesnik512

AGENTS.md

@@ -28,6 +28,10 @@ for what it does; read them. What reading a single module will **not** tell you:
 - The `SERVICE_KEYS` / `STRUCTURAL_KEYS` split in `keys.py` is a design ruling about which keys can
   share one `emit(value)` interface, not a leftover. A new key belongs in the registry only if
   it fits that signature without widening it.
+- `compose2pod/podman.py` is not a pipeline stage: it holds every claim the tool makes about
+  podman's behaviour, so a refusal citing podman can be enumerated rather than grepped for.
+  `tests/test_podman_claim_coverage.py` requires each claim to be measured against real podman.
+  A new refusal whose reason is podman's belongs there, or the gate goes red.
 - `tests/conformance/` generates its probe matrix from
   `SERVICE_KEYS | STRUCTURAL_KEYS | IGNORED_SERVICE_KEYS`, so adding a key probes it against
   `docker compose config` automatically. It is CI-only (`just test-conformance`,

compose2pod/parsing.py

@@ -4,7 +4,7 @@
 from collections.abc import Callable
 from typing import Any
 
-from compose2pod import stores, values
+from compose2pod import podman, stores, values
 from compose2pod.exceptions import UnsupportedComposeError
 from compose2pod.graph import depends_on, hostnames
 from compose2pod.healthcheck import has_healthcheck, health_cmd, interval_seconds
@@ -200,7 +200,7 @@ def _reject_drive_shaped_volume(name: str, volume: str) -> None:
         raise UnsupportedComposeError(msg)
     msg = (
         f"{preamble}an anonymous volume whose target is the whole string, and "
-        "podman refuses a container path that is not absolute "
+        f"{podman.REFUSES_RELATIVE_CONTAINER_PATH} "
         "(name a one-character volume through the long form instead)"
     )
     raise UnsupportedComposeError(msg)
@@ -219,10 +219,6 @@ def _reject_drive_shaped_volume(name: str, volume: str) -> None:
     "tmpfs": {"size", "mode"},
     "image": {"subpath"},
 }
-# compose2pod supports podman 4.9 and up (README, docs/adr/0006-docker-rejection-parity.md):
-# a form is accepted only when podman expresses it across that whole range, so a key
-# that arrives in a later podman is refused until the floor reaches it.
-_PODMAN_FLOOR = "4.9"
 _PROPAGATION_VALUES = {"private", "rprivate", "shared", "rshared", "slave", "rslave"}
 _SELINUX_VALUES = {"z", "Z"}
 
@@ -310,7 +306,7 @@ def _validate_bind_options(name: str, options: dict[str, Any]) -> None:
     folded into the generic unknown-key check the caller already ran.
     """
     if "create_host_path" in options:
-        msg = f"service {name!r}: bind 'create_host_path' is not supported (podman cannot express it)"
+        msg = f"service {name!r}: bind 'create_host_path' is not supported ({podman.CANNOT_EXPRESS})"
         raise UnsupportedComposeError(msg)
     if "propagation" in options and options["propagation"] not in _PROPAGATION_VALUES:
         msg = f"service {name!r}: bind 'propagation' must be one of {sorted(_PROPAGATION_VALUES)}"
@@ -322,10 +318,7 @@ def _validate_bind_options(name: str, options: dict[str, Any]) -> None:
 
 def _reject_subpath(name: str, vtype: str, added_in: str) -> None:
     """Refuse a nested `subpath`: podman gained the mount option after the supported floor."""
-    msg = (
-        f"service {name!r}: {vtype} 'subpath' is not supported "
-        f"(podman {added_in} adds the mount option, and compose2pod supports podman {_PODMAN_FLOOR} and up)"
-    )
+    msg = f"service {name!r}: {vtype} 'subpath' is not supported ({podman.adds_the_mount_option_in(added_in)})"
     raise UnsupportedComposeError(msg)
 
 
@@ -344,7 +337,7 @@ def _validate_volume_type_options(name: str, options: dict[str, Any]) -> None:
     if "nocopy" in options:
         msg = (
             f"service {name!r}: volume 'nocopy' is not supported here: the long form mounts with "
-            "--mount, whose grammar has no nocopy (use the short syntax, which emits -v and podman honours)"
+            f"--mount, whose grammar has no nocopy ({podman.NOCOPY_NEEDS_THE_SHORT_FORM})"
         )
         raise UnsupportedComposeError(msg)
     if "subpath" in options:

compose2pod/podman.py

@@ -0,0 +1,27 @@
+"""Every claim compose2pod makes about podman, in one place.
+
+A refusal whose reason is podman's behaviour draws its clause from here instead of
+spelling one inline. The point is not the wording, which changes freely, but the name:
+`tests/test_podman_claim_coverage.py` reads this module's attributes to find the sites
+that make such a claim, and requires each one to be measured by a row in
+`tests/integration/refusals.py`. Grepping for prose cannot do that -- the message is
+assembled from an f-string, a shared preamble or a lookup table, depending on the site.
+
+That gate is what issue #86 was missing: an unmeasured "podman can express it" became
+#104's shipped acceptance of a script that dies at `podman run`.
+"""
+
+# compose2pod supports podman FLOOR and up (README, docs/adr/0006-docker-rejection-parity.md).
+# A form is accepted only where podman expresses it across that whole range.
+FLOOR = "4.9"
+
+CANNOT_EXPRESS = "podman cannot express it"
+REFUSES_RELATIVE_CONTAINER_PATH = "podman refuses a container path that is not absolute"
+NOCOPY_NEEDS_THE_SHORT_FORM = "use the short syntax, which emits -v and podman honours"
+NO_RESERVATION_FLAG = "podman run has no reservation flag for it"
+GPUS_RESERVES_NOTHING = "podman run's --gpus accepts any value and reserves nothing"
+
+
+def adds_the_mount_option_in(version: str) -> str:
+    """Spell the clause for a mount option podman gained above the floor."""
+    return f"podman {version} adds the mount option, and compose2pod supports podman {FLOOR} and up"

compose2pod/resources.py

@@ -3,7 +3,7 @@
 from collections.abc import Callable
 from typing import Any
 
-from compose2pod import values
+from compose2pod import podman, values
 from compose2pod.exceptions import UnsupportedComposeError
 from compose2pod.keys import Expand, Token, require_string_keys
 
@@ -53,8 +53,8 @@ def _validate_limits(name: str, svc: dict[str, Any], limits: Any) -> None:  # no
 # podman run has, and `--gpus` exists but is hidden and accepts `nonsense` as
 # readily as `all`, so emitting it would reserve nothing and say it had.
 _RESERVATION_REFUSALS = {
-    "cpus": "podman run has no reservation flag for it",
-    "devices": "podman run's --gpus accepts any value and reserves nothing",
+    "cpus": podman.NO_RESERVATION_FLAG,
+    "devices": podman.GPUS_RESERVES_NOTHING,
 }
 
 

docs/adr/0006-docker-rejection-parity.md

@@ -32,10 +32,15 @@ flag podman does not have and `STUB_FLAGS` for one it has that validates nothing
 `nonsense` is a worse reason to emit it than a flag that fails, since the script would report
 success for something it never did. `tests/integration/acceptances.py` runs the
 mirror image, every flag a long-form mount compiles to, because a rule-two claim fails in both
-directions: #104 and #114 each shipped a form the gate accepted and podman would not run. A gate
-that every rule-two site has a row is
-[#109](https://github.com/modern-python/compose2pod/issues/109) phase 3, and it has to carry the
-exemptions first: not every refusal this document names turns out to be one podman makes.
+directions: #104 and #114 each shipped a form the gate accepted and podman would not run. What keeps
+the two in step is `compose2pod/podman.py`: every refusal whose reason is podman's behaviour draws
+its clause from there, and `tests/test_podman_claim_coverage.py` pairs each site that makes a claim
+with the row that measures it, in both directions. The handle is the attribute name, not the
+wording, because prose is not a registry -- a message is assembled from an f-string, a shared
+preamble or a lookup table depending on the site. A refusal that makes no claim is out of scope by
+construction, which is how `network_mode` needs no row; a refusal whose reason is podman's but whose
+message keeps that to itself is invisible to the gate, and that list is
+[#121](https://github.com/modern-python/compose2pod/issues/121).
 Verdicts are per version, and the supported range is stated rather than implied: the rulings here
 are measured against `docker compose config` v5.1.2 and podman 4.9.3, and compose2pod supports
 podman 4.9 and up. Rule two reads across that whole range. A form is accepted only where podman

tests/integration/refusals.py

@@ -28,6 +28,12 @@
 - `STUB_FLAGS` -- the flag exists and accepts deliberate nonsense, so emitting it would
   exit 0 having done nothing, which is worse than refusing.
 
+A row measuring a refusal whose message draws a clause from `compose2pod/podman.py` names
+the `site` that makes the claim and the `claim` it makes, which is what
+`tests/test_podman_claim_coverage.py` gates on. A row whose refusal makes no such claim --
+a relative target, an unsupported long-form `type` -- leaves both empty: the reason is
+podman's, but the message keeps it to itself, which is issue #121's subject.
+
 Four claims, four experiments. `network_mode` alone has no row: it is refused under
 ADR-0003, not rule two, and podman honours it (#115). The gate that every rule-two site
 has a row is issue #109 phase 3, and that is the exemption it has to know about.
@@ -54,6 +60,8 @@ class Refusal:
     refusal_match: str
     podman_argv: list[str]
     control_argv: list[str]
+    site: str = ""
+    claim: str = ""
 
 
 @dataclass(frozen=True)
@@ -71,6 +79,8 @@ class Limitation:
     refusal_match: str
     podman_argv: list[str]
     host_dir: str = ""
+    site: str = ""
+    claim: str = ""
 
 
 @dataclass(frozen=True)
@@ -85,6 +95,8 @@ class AbsentFlag:
     compose: dict[str, Any]
     refusal_match: str
     unknown_argv: list[list[str]]
+    site: str = ""
+    claim: str = ""
 
 
 @dataclass(frozen=True)
@@ -99,6 +111,8 @@ class StubFlag:
     compose: dict[str, Any]
     refusal_match: str
     nonsense_argv: list[str]
+    site: str = ""
+    claim: str = ""
 
 
 def _one_volume(entry: "str | dict[str, Any]") -> dict[str, Any]:
@@ -126,20 +140,26 @@ def _one_volume(entry: "str | dict[str, Any]") -> dict[str, Any]:
     ),
     Refusal(
         id="drive-shaped-source-no-target",
+        site="parsing._reject_drive_shaped_volume",
+        claim="REFUSES_RELATIVE_CONTAINER_PATH",
         compose=_one_volume("C:\\data"),
         refusal_match=_NOT_ABSOLUTE,
         podman_argv=["--mount", "type=volume,dst=C:\\data"],
         control_argv=_ANONYMOUS_CONTROL,
     ),
     Refusal(
         id="single-letter-source-with-path",
+        site="parsing._reject_drive_shaped_volume",
+        claim="REFUSES_RELATIVE_CONTAINER_PATH",
         compose=_one_volume("v:/data"),
         refusal_match=_NOT_ABSOLUTE,
         podman_argv=["--mount", "type=volume,dst=v:/data"],
         control_argv=_ANONYMOUS_CONTROL,
     ),
     Refusal(
         id="single-letter-source-empty-target",
+        site="parsing._reject_drive_shaped_volume",
+        claim="REFUSES_RELATIVE_CONTAINER_PATH",
         compose=_one_volume("v:"),
         refusal_match=_NOT_ABSOLUTE,
         podman_argv=["--mount", "type=volume,dst=v:"],
@@ -169,6 +189,8 @@ def _one_volume(entry: "str | dict[str, Any]") -> dict[str, Any]:
     Refusal(
         # Measured: podman creates a missing bind source in no spelling, `-v` or `--mount`.
         id="bind-create-host-path",
+        site="parsing._validate_bind_options",
+        claim="CANNOT_EXPRESS",
         compose=_one_volume({"type": "bind", "source": "./src", "target": "/var", "bind": {"create_host_path": True}}),
         refusal_match="bind 'create_host_path' is not supported",
         podman_argv=["--mount", "type=bind,src={host}/absent,dst=/var"],
@@ -177,6 +199,8 @@ def _one_volume(entry: "str | dict[str, Any]") -> dict[str, Any]:
     Refusal(
         # `source=`/`target=` rather than the `src=`/`dst=` above: the spelling #114 measured.
         id="image-subpath",
+        site="parsing._reject_subpath",
+        claim="adds_the_mount_option_in",
         compose=_one_volume(
             {"type": "image", "source": "busybox:1.36", "target": "/mnt", "image": {"subpath": "/bin"}}
         ),
@@ -186,6 +210,8 @@ def _one_volume(entry: "str | dict[str, Any]") -> dict[str, Any]:
     ),
     Refusal(
         id="volume-subpath",
+        site="parsing._reject_subpath",
+        claim="adds_the_mount_option_in",
         compose=_one_volume({"type": "volume", "target": "/mnt", "volume": {"subpath": "/sub"}}),
         refusal_match="volume 'subpath' is not supported",
         podman_argv=["--mount", "type=volume,target=/mnt,subpath=/sub"],
@@ -203,6 +229,8 @@ def _reservation(field: str, value: object) -> dict[str, Any]:
         # Measured: `-v vol:/etc:nocopy` leaves only podman's own hosts/hostname/resolv.conf
         # in the volume, so the image copy-up really is suppressed.
         id="volume-nocopy",
+        site="parsing._validate_volume_type_options",
+        claim="NOCOPY_NEEDS_THE_SHORT_FORM",
         compose={
             "services": {
                 "app": {
@@ -235,6 +263,8 @@ def _reservation(field: str, value: object) -> dict[str, Any]:
 ABSENT_FLAGS: list[AbsentFlag] = [
     AbsentFlag(
         id="reservations-cpus",
+        site="resources._RESERVATION_REFUSALS",
+        claim="NO_RESERVATION_FLAG",
         compose=_reservation("cpus", "0.5"),
         refusal_match="podman run has no reservation flag for it",
         unknown_argv=[["--cpu-reservation", "1"], ["--cpus-reservation", "1"]],
@@ -245,6 +275,8 @@ def _reservation(field: str, value: object) -> dict[str, Any]:
 STUB_FLAGS: list[StubFlag] = [
     StubFlag(
         id="reservations-devices",
+        site="resources._RESERVATION_REFUSALS",
+        claim="GPUS_RESERVES_NOTHING",
         compose=_reservation("devices", [{"capabilities": ["gpu"]}]),
         refusal_match="--gpus accepts any value and reserves nothing",
         nonsense_argv=["--gpus", "nonsense"],

tests/test_podman_claim_coverage.py

@@ -0,0 +1,124 @@
+import ast
+import pathlib
+import typing
+
+from compose2pod import podman
+from tests.integration.refusals import ABSENT_FLAGS, LIMITATIONS, REFUSALS, STUB_FLAGS
+
+
+_PACKAGE: typing.Final = pathlib.Path(__file__).resolve().parent.parent / "compose2pod"
+_CLAIMS_MODULE: typing.Final = "podman"
+
+
+def _site_of(statement: ast.stmt) -> str:
+    if isinstance(statement, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)):
+        return statement.name
+    targets = getattr(statement, "targets", [])
+    return next((target.id for target in targets if isinstance(target, ast.Name)), "")
+
+
+def _claims_in(statement: ast.stmt) -> set[str]:
+    return {
+        node.attr
+        for node in ast.walk(statement)
+        if isinstance(node, ast.Attribute) and isinstance(node.value, ast.Name) and node.value.id == _CLAIMS_MODULE
+    }
+
+
+def claim_sites(package: pathlib.Path) -> set[tuple[str, str]]:
+    """Every (site, claim) pair in a package: where it draws a clause from the claims module.
+
+    A site is the top-level function, class or assignment that holds the reference, named
+    `<module>.<site>` -- the granularity a measurement is written at. The scan reads
+    attribute access rather than message text because a message is assembled from an
+    f-string, a shared preamble or a lookup table depending on the site, and prose is not
+    a registry.
+    """
+    found: set[tuple[str, str]] = set()
+    for file in sorted(package.glob("*.py")):
+        if file.stem == _CLAIMS_MODULE:
+            continue
+        for statement in ast.parse(file.read_text(encoding="utf-8")).body:
+            site = _site_of(statement)
+            found |= {(f"{file.stem}.{site}", claim) for claim in _claims_in(statement) if site}
+    return found
+
+
+def _measured_pairs() -> set[tuple[str, str]]:
+    return {
+        (row.site, row.claim)
+        for table in (REFUSALS, LIMITATIONS, ABSENT_FLAGS, STUB_FLAGS)
+        for row in table
+        if row.site
+    }
+
+
+def test_every_claim_compose2pod_makes_about_podman_is_measured_by_a_row() -> None:
+    """INVARIANT: a refusal whose reason is podman's behaviour is measured against real podman.
+
+    Broken by adding a refusal that draws a clause from `compose2pod/podman.py` without a row
+    in `tests/integration/refusals.py`. That is issue #86's mistake mechanised: an asserted
+    "podman cannot express it" became #104's shipped acceptance of a script that dies at
+    `podman run`, and #114 repeated it from the other side.
+
+    Out of scope by construction: a refusal that makes no claim here. `network_mode` is
+    refused under docs/adr/0003-the-shared-namespace-decides-key-classification.md and podman
+    honours it, so it has no claim and needs no row. A refusal whose reason *is* podman's but
+    whose message keeps that to itself is invisible to this gate, which is issue #121.
+    """
+    unmeasured = sorted(claim_sites(_PACKAGE) - _measured_pairs())
+
+    assert unmeasured == [], "\n".join(
+        f"{site} claims podman.{claim} and no row measures it" for site, claim in unmeasured
+    )
+
+
+def test_every_row_naming_a_claim_names_one_the_source_still_makes() -> None:
+    """INVARIANT: a row measures a claim that exists, at the site that makes it.
+
+    Broken by renaming a claim, moving a refusal to another function, or dropping the refusal
+    and leaving the row behind. A row that measures nothing passes forever.
+    """
+    stale = sorted(_measured_pairs() - claim_sites(_PACKAGE))
+
+    assert stale == [], "\n".join(f"row claims {site} uses podman.{claim}; it does not" for site, claim in stale)
+
+
+def test_every_claim_a_row_names_is_an_attribute_of_the_claims_module() -> None:
+    """A typo in a row's `claim` would otherwise pair with a typo in the scan and cancel out."""
+    missing = sorted({claim for _, claim in _measured_pairs() if not hasattr(podman, claim)})
+
+    assert missing == []
+
+
+def test_a_claim_made_with_no_row_is_reported_with_its_site(tmp_path: pathlib.Path) -> None:
+    """The scanner is exercised against a known result, so an empty scan cannot pass as a green one."""
+    (tmp_path / "parsing.py").write_text(
+        "from compose2pod import podman\n\n\ndef _refuse():\n    raise ValueError(podman.CANNOT_EXPRESS)\n",
+        encoding="utf-8",
+    )
+
+    assert claim_sites(tmp_path) == {("parsing._refuse", "CANNOT_EXPRESS")}
+
+
+def test_a_claim_held_in_a_module_level_table_is_found(tmp_path: pathlib.Path) -> None:
+    """`resources.py` keeps its two reservation clauses in a dict, outside any function."""
+    (tmp_path / "resources.py").write_text(
+        "from compose2pod import podman\n\n_REFUSALS = {'cpus': podman.NO_RESERVATION_FLAG}\n",
+        encoding="utf-8",
+    )
+
+    assert claim_sites(tmp_path) == {("resources._REFUSALS", "NO_RESERVATION_FLAG")}
+
+
+def test_the_claims_module_is_not_scanned_against_itself(tmp_path: pathlib.Path) -> None:
+    """Its own helper spells a clause from `FLOOR`, which is a definition, not a claim made."""
+    (tmp_path / "podman.py").write_text("FLOOR = '4.9'\n\n\ndef clause():\n    return podman.FLOOR\n", encoding="utf-8")
+
+    assert claim_sites(tmp_path) == set()
+
+
+def test_a_module_naming_nothing_from_the_claims_module_contributes_no_pairs(tmp_path: pathlib.Path) -> None:
+    (tmp_path / "graph.py").write_text("def walk():\n    return 1\n", encoding="utf-8")
+
+    assert claim_sites(tmp_path) == set()