@amsterdamdatalabs/adl-agent-control-linux-x64 0.1.12 → 0.1.26

package/packages/repo-controls/package/adl-compliance/src/adl_compliance/checks/repository/lockfile_integrity/test_stale_lock.py

@@ -0,0 +1,1179 @@
+"""REP-002 `LCK-002` grades the CONTENT of a `Cargo.lock`, not only cargo's exit code.
+
+The hole this pins (measured through the real check on 2026-10-01, probe
+`.scratchpad/rep002-scope/probe_stale.py`): the gate ran `cargo metadata --locked
+--offline --no-deps` and reported `LCK-002` only when it exited non-zero. With
+`--no-deps` cargo never resolves, so it never reads `Cargo.lock`: a lock that was
+`version = 4` alone, one that was not TOML, and one with `version = 99` all came
+out CLEAN, and only a missing or empty lock was ever reported.
+
+The validation under test is deterministic Python (`tomllib`): it reads the lock,
+the workspace manifest, the member manifests and the path-dependency manifests the
+manifest text names, and nothing else. No cargo, no registry, no network.
+
+Two kinds of test, and why:
+
+  * Most tests grade through the real dispatch path (`runner.run`) with the two
+    cargo subprocess calls replaced by a recorder that exits 0 (`cargo_accepts`),
+    the same technique `test_declared_paths.py` uses for the cargo cwd pin. The
+    content validation never asks cargo anything, so these tests need no toolchain
+    and cannot depend on a machine's registry cache; the recorder also pins that
+    cargo is asked exactly the two questions it always was.
+  * A few tests (`requires_cargo`) run the REAL `cargo metadata --no-deps` against
+    hand-written manifests, so the integration with the real command is proven too.
+
+Fixtures are hand-written text, never generated by cargo: a valid lock is TOML
+(`version = 3`, `[[package]]` with `name`/`version`/`source`/`checksum`), and a
+path package (a workspace member, a path dependency) has no `source`.
+"""
+
+from __future__ import annotations
+
+import shutil
+from collections.abc import Mapping
+from pathlib import Path
+from types import SimpleNamespace
+from typing import NamedTuple
+
+import pytest
+from fixture_trees import fixture_trees
+from helpers import corpus_files
+
+from adl_compliance import runner
+from adl_compliance.checks.repository.lockfile_integrity import check as module
+from adl_compliance.core.verdict import Outcome, Verdict
+from adl_compliance.policy.registry import load
+
+ROW = load().by_id("REP-002")
+
+requires_cargo = pytest.mark.skipif(shutil.which("cargo") is None, reason="cargo is not installed")
+
+REGISTRY = "registry+https://github.com/rust-lang/crates.io-index"
+HEADER = "# This file is automatically @generated by Cargo.\n# It is not intended for manual editing.\n"
+FIX = (
+    "run: (cd backend && cargo update) to resync backend/Cargo.lock with "
+    "backend/Cargo.toml, then commit the result"
+)
+
+
+# ------------------------------------------------------------------- the fixtures
+
+
+class Pkg(NamedTuple):
+    name: str
+    version: str = "1.0.0"
+    path: bool = False
+    """A path package (workspace member, path dependency): no `source` in the lock."""
+    needs: tuple[str, ...] = ()
+    """The strings of this package's `dependencies = [...]`, verbatim."""
+
+    def text(self) -> str:
+        lines = ["[[package]]", f'name = "{self.name}"', f'version = "{self.version}"']
+        if not self.path:
+            lines += [f'source = "{REGISTRY}"', f'checksum = "{"0" * 64}"']
+        if self.needs:
+            lines += ["dependencies = [", *(f' "{need}",' for need in self.needs), "]"]
+        return "\n".join(lines) + "\n"
+
+
+def lock_text(packages: tuple[Pkg, ...], *, version: int | None = 3) -> str:
+    head = HEADER + (f"version = {version}\n" if version is not None else "")
+    return head + "\n" + "\n".join(pkg.text() for pkg in packages)
+
+
+def without(packages: tuple[Pkg, ...], *names: str) -> tuple[Pkg, ...]:
+    """What `cargo update` would NOT write if `names` were never needed: the packages are gone
+    and no remaining package lists them either."""
+    return tuple(
+        p._replace(needs=tuple(n for n in p.needs if n.partition(" ")[0] not in names))
+        for p in packages
+        if p.name not in names
+    )
+
+
+class Shape(NamedTuple):
+    """A manifest tree (paths relative to the cargo workspace) and the lock packages it needs.
+
+    A member's `needs` are the direct dependencies of its manifests, as cargo writes them."""
+
+    files: dict[str, str]
+    packages: tuple[Pkg, ...]
+
+    def lock(self, *, drop: tuple[str, ...] = (), swap: Mapping[str, Pkg] | None = None) -> str:
+        swap = swap or {}
+        kept = without(self.packages, *drop)
+        return lock_text(tuple(swap.get(p.name, p) for p in kept))
+
+
+SINGLE = Shape(
+    files={
+        "Cargo.toml": """\
+[package]
+name = "app"
+version = "0.1.0"
+edition = "2021"
+
+[dependencies]
+serde = "1"
+sj = { package = "serde_json_fork", version = "1" }
+opt = { version = "1", optional = true }
+
+[dev-dependencies]
+pretty_assertions = "1"
+
+[build-dependencies]
+cc = "1"
+
+[target.'cfg(windows)'.dependencies]
+winapi = "0.3"
+
+[target.'cfg(unix)'.build-dependencies]
+pkg-config = "0.3"
+
+[target.'cfg(unix)'.dev-dependencies]
+tempfile = "3"
+"""
+    },
+    packages=(
+        Pkg(
+            "app",
+            "0.1.0",
+            path=True,
+            needs=(
+                "serde",
+                "serde_json_fork",
+                "opt",
+                "pretty_assertions",
+                "cc",
+                "winapi",
+                "pkg-config",
+                "tempfile",
+            ),
+        ),
+        Pkg("serde"),
+        Pkg("serde_json_fork"),
+        Pkg("opt"),
+        Pkg("pretty_assertions"),
+        Pkg("cc"),
+        Pkg("winapi", "0.3.9"),
+        Pkg("pkg-config", "0.3.30"),
+        Pkg("tempfile", "3.10.0"),
+    ),
+)
+
+# (real package name, the key it is declared under, the section it is declared in)
+SINGLE_DEPENDENCIES = [
+    pytest.param("serde", "serde", "[dependencies]", id="normal"),
+    pytest.param("serde_json_fork", "sj", "[dependencies]", id="renamed via package="),
+    pytest.param("opt", "opt", "[dependencies]", id="optional"),
+    pytest.param("pretty_assertions", "pretty_assertions", "[dev-dependencies]", id="dev"),
+    pytest.param("cc", "cc", "[build-dependencies]", id="build"),
+    pytest.param("winapi", "winapi", "[target.'cfg(windows)'.dependencies]", id="target normal"),
+    pytest.param(
+        "pkg-config", "pkg-config", "[target.'cfg(unix)'.build-dependencies]", id="target build"
+    ),
+    pytest.param(
+        "tempfile", "tempfile", "[target.'cfg(unix)'.dev-dependencies]", id="target dev"
+    ),
+]
+
+VIRTUAL = Shape(
+    files={
+        "Cargo.toml": """\
+[workspace]
+resolver = "2"
+members = ["crates/*"]
+exclude = ["crates/skipped"]
+
+[workspace.package]
+version = "0.3.0"
+edition = "2021"
+
+[workspace.dependencies]
+serde = { version = "1", features = ["derive"] }
+log = "0.4"
+renamed = { package = "real_name", version = "2" }
+core-lib = { path = "crates/core-lib" }
+unused = "1"
+""",
+        "crates/core-lib/Cargo.toml": """\
+[package]
+name = "core-lib"
+version.workspace = true
+edition.workspace = true
+""",
+        "crates/web/Cargo.toml": """\
+[package]
+name = "web"
+version = "0.1.0"
+edition = "2021"
+
+[dependencies]
+serde.workspace = true
+core-lib = { workspace = true }
+renamed = { workspace = true, optional = true }
+
+[dev-dependencies]
+log = { workspace = true }
+""",
+        "crates/skipped/Cargo.toml": """\
+[package]
+name = "skipped"
+version = "9.9.9"
+edition = "2021"
+
+[dependencies]
+only-skipped = "1"
+""",
+    },
+    packages=(
+        Pkg("core-lib", "0.3.0", path=True),
+        Pkg("web", "0.1.0", path=True, needs=("serde", "core-lib", "real_name", "log")),
+        Pkg("serde"),
+        Pkg("log", "0.4.21"),
+        Pkg("real_name", "2.0.0"),
+    ),
+)
+
+# A root package that is also a workspace; `helper` is a path dependency living inside the
+# root and listed nowhere in `members`: cargo makes it a member, so ITS dependencies are locked.
+IMPLICIT = Shape(
+    files={
+        "Cargo.toml": """\
+[package]
+name = "root"
+version = "0.1.0"
+edition = "2021"
+
+[workspace]
+members = ["member-a"]
+
+[dependencies]
+h = { path = "helper", package = "helper" }
+""",
+        "member-a/Cargo.toml": """\
+[package]
+name = "member-a"
+version = "0.2.0"
+edition = "2021"
+
+[dependencies]
+shared = { path = "../../shared" }
+""",
+        "helper/Cargo.toml": """\
+[package]
+name = "helper"
+version = "0.4.0"
+edition = "2021"
+
+[dependencies]
+helper-dep = "1"
+""",
+        "../shared/Cargo.toml": """\
+[package]
+name = "shared"
+version = "0.5.0"
+edition = "2021"
+""",
+    },
+    packages=(
+        Pkg("root", "0.1.0", path=True, needs=("helper",)),
+        Pkg("member-a", "0.2.0", path=True, needs=("shared",)),
+        Pkg("helper", "0.4.0", path=True, needs=("helper-dep",)),
+        Pkg("shared", "0.5.0", path=True),
+        Pkg("helper-dep"),
+    ),
+)
+
+SHAPES = [
+    pytest.param(SINGLE, id="single package, every dependency table"),
+    pytest.param(VIRTUAL, id="virtual workspace, members glob + exclude + inheritance"),
+    pytest.param(IMPLICIT, id="root package and workspace, implicit path-dependency member"),
+]
+
+
+def lay(root: Path, files: Mapping[str, str], lock: str | bytes, *, where: str = "backend") -> None:
+    """Write a cargo workspace under `root/where` plus the TypeScript lock the gate also wants.
+
+    A manifest with a `[package]` gets a `src/lib.rs`, so the very same files are also valid
+    input to the real `cargo metadata`. `where` is the cargo workspace directory.
+    """
+    base = root / where
+    for relative, body in files.items():
+        target = (base / relative).resolve()
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_text(body, encoding="utf-8")
+        if "[package]" in body:
+            (target.parent / "src").mkdir(exist_ok=True)
+            (target.parent / "src" / "lib.rs").write_text("", encoding="utf-8")
+    lockfile = base / "Cargo.lock"
+    if isinstance(lock, bytes):
+        lockfile.write_bytes(lock)
+    else:
+        lockfile.write_text(lock, encoding="utf-8")
+    (root / "frontend").mkdir(exist_ok=True)
+    (root / "frontend" / "bun.lock").write_text("# fixture lock\n", encoding="utf-8")
+
+
+def grade(
+    root: Path, *, declarations: Mapping[str, str] | None = None, trees: Mapping[str, str] | None = None
+) -> Verdict:
+    """The real dispatch path, whole tree, exhaustive."""
+    trees = fixture_trees() if trees is None else trees
+    files = corpus_files(root)
+    return runner.run(
+        ROW,
+        root,
+        files,
+        exhaustive=True,
+        universe=files,
+        declarations=declarations or {},
+        trees=trees,
+        declared_trees=trees,
+    )
+
+
+def messages(verdict: Verdict) -> list[str]:
+    return [finding.message for finding in verdict.findings]
+
+
+def stale_lock(tmp_path: Path, files: Mapping[str, str], lock: str | bytes) -> Verdict:
+    lay(tmp_path, files, lock)
+    return grade(tmp_path)
+
+
+@pytest.fixture
+def cargo_accepts(monkeypatch: pytest.MonkeyPatch) -> list[list[str]]:
+    """Both cargo calls succeed; returns every argv the check spawned."""
+    argvs: list[list[str]] = []
+
+    def fake_run(argv: list[str], *, cwd: Path, **_: object) -> object:
+        argvs.append(argv)
+        return SimpleNamespace(returncode=0)
+
+    monkeypatch.setattr(module.shutil, "which", lambda name: "/fake/cargo")
+    monkeypatch.setattr(module.subprocess, "run", fake_run)
+    return argvs
+
+
+# --------------------------------------------- the three locks the previous probe measured
+
+GARBAGE = [
+    pytest.param("version = 4\n", "backend/Cargo.lock lists no packages", id="version = 4 alone"),
+    pytest.param("this is [[ not a lockfile\n", "backend/Cargo.lock is not valid TOML", id="not TOML"),
+    pytest.param(
+        "version = 99\n", "backend/Cargo.lock version 99 is not supported", id="version = 99"
+    ),
+]
+
+
+@pytest.mark.parametrize(("body", "expected"), GARBAGE)
+def test_a_garbage_lock_is_lck_002(
+    tmp_path: Path, cargo_accepts: list[list[str]], body: str, expected: str
+) -> None:
+    verdict = stale_lock(tmp_path, SINGLE.files, body)
+    assert verdict.outcome is Outcome.FINDINGS, verdict.render()
+    assert {f.rule for f in verdict.findings} == {"LCK-002"}
+    assert {f.path for f in verdict.findings} == {"backend/Cargo.lock"}
+    assert any(message.startswith(expected) for message in messages(verdict)), messages(verdict)
+
+
+@requires_cargo
+@pytest.mark.parametrize(("body", "expected"), GARBAGE)
+def test_a_garbage_lock_is_lck_002_with_the_real_cargo_command(
+    tmp_path: Path, body: str, expected: str
+) -> None:
+    """The very bodies the real `cargo metadata --no-deps` accepted: the gate now rejects them."""
+    verdict = stale_lock(tmp_path, SINGLE.files, body)
+    assert verdict.outcome is Outcome.FINDINGS, verdict.render()
+    assert {f.rule for f in verdict.findings} == {"LCK-002"}
+    assert any(message.startswith(expected) for message in messages(verdict)), messages(verdict)
+
+
+def test_a_lock_that_is_not_utf8_is_lck_002(tmp_path: Path, cargo_accepts: list[list[str]]) -> None:
+    verdict = stale_lock(tmp_path, SINGLE.files, b"\xff\xfe\x00 not text \x80")
+    assert messages(verdict) == ["backend/Cargo.lock is not valid UTF-8 text"]
+
+
+# ---------------------------------------------------------------- the lock's structure
+
+
+@pytest.mark.parametrize("version", [3, 4, None], ids=["version = 3", "version = 4", "no version (V1/V2)"])
+def test_a_supported_lock_version_is_clean(
+    tmp_path: Path, cargo_accepts: list[list[str]], version: int | None
+) -> None:
+    """cargo 0.99.0, `EncodableResolve::into_resolve`: `Some(4)`, `Some(3)` and, with no
+    `version` key at all, the legacy V1/V2 encodings are read; anything else is refused."""
+    body = lock_text(SINGLE.packages, version=version)
+    verdict = stale_lock(tmp_path, SINGLE.files, body)
+    assert verdict.outcome is Outcome.CLEAN, verdict.render()
+
+
+@pytest.mark.parametrize(
+    "line",
+    ["version = 1", "version = 2", "version = 5", "version = 0", "version = -3", "version = 99"],
+)
+def test_an_unsupported_integer_lock_version_is_reported(
+    tmp_path: Path, cargo_accepts: list[list[str]], line: str
+) -> None:
+    number = line.split("= ")[1]
+    body = HEADER + line + "\n\n" + "\n".join(p.text() for p in SINGLE.packages)
+    verdict = stale_lock(tmp_path, SINGLE.files, body)
+    assert messages(verdict) == [
+        f"backend/Cargo.lock version {number} is not supported (cargo reads lock versions 3 and 4)"
+    ]
+
+
+@pytest.mark.parametrize(
+    ("line", "shown"),
+    [('version = "4"', "'4'"), ("version = 4.0", "4.0"), ("version = true", "True")],
+    ids=["string", "float", "boolean"],
+)
+def test_a_lock_version_that_is_not_an_integer_is_reported(
+    tmp_path: Path, cargo_accepts: list[list[str]], line: str, shown: str
+) -> None:
+    body = HEADER + line + "\n\n" + "\n".join(p.text() for p in SINGLE.packages)
+    verdict = stale_lock(tmp_path, SINGLE.files, body)
+    assert messages(verdict) == [
+        f"backend/Cargo.lock version {shown} is not supported (cargo reads lock versions 3 and 4)"
+    ]
+
+
+@pytest.mark.parametrize(
+    "body",
+    [
+        pytest.param("version = 3\n", id="no [[package]]"),
+        pytest.param("version = 3\npackage = []\n", id="empty package array"),
+    ],
+)
+def test_a_lock_without_packages_is_reported(
+    tmp_path: Path, cargo_accepts: list[list[str]], body: str
+) -> None:
+    verdict = stale_lock(tmp_path, SINGLE.files, body)
+    assert messages(verdict) == [
+        "backend/Cargo.lock lists no packages ([[package]] is absent or empty)"
+    ]
+
+
+def test_an_empty_package_table_is_reported(tmp_path: Path, cargo_accepts: list[list[str]]) -> None:
+    body = "version = 3\n\n[[package]]\n"
+    verdict = stale_lock(tmp_path, SINGLE.files, body)
+    assert messages(verdict) == [
+        "backend/Cargo.lock has a [[package]] entry (number 1) without a string name"
+    ]
+
+
+@pytest.mark.parametrize(
+    ("entry", "expected"),
+    [
+        pytest.param('version = "1.0.0"\n', "without a string name", id="no name"),
+        pytest.param('name = "x"\n', "without a string version", id="no version"),
+        pytest.param('name = 7\nversion = "1.0.0"\n', "without a string name", id="name not a string"),
+        pytest.param('name = "x"\nversion = 1\n', "without a string version", id="version not a string"),
+    ],
+)
+def test_a_package_entry_without_name_or_version_is_reported(
+    tmp_path: Path, cargo_accepts: list[list[str]], entry: str, expected: str
+) -> None:
+    good = "\n".join(p.text() for p in SINGLE.packages)
+    body = HEADER + "version = 3\n\n" + good + "\n[[package]]\n" + entry
+    verdict = stale_lock(tmp_path, SINGLE.files, body)
+    number = len(SINGLE.packages) + 1
+    assert messages(verdict) == [f"backend/Cargo.lock has a [[package]] entry (number {number}) {expected}"]
+
+
+def test_a_package_entry_that_is_not_a_table_is_reported(
+    tmp_path: Path, cargo_accepts: list[list[str]]
+) -> None:
+    verdict = stale_lock(tmp_path, SINGLE.files, "version = 3\npackage = [1]\n")
+    assert messages(verdict) == [
+        "backend/Cargo.lock has a [[package]] entry (number 1) that is not a table"
+    ]
+
+
+# ------------------------------------- the lock must hold every package it says it needs
+
+# The shapes cargo writes `dependencies = [...]` in (V1 to V4): a bare name when only one
+# version of it is locked, `name version` when several are, `name version (source)` when
+# several sources are. A package that was removed from the lock but is still listed by a
+# dependent is a lock cargo refuses to parse, and it passed too.
+CLOSED = (
+    Pkg("app", "0.1.0", path=True, needs=("serde", "twice 1.0.0", f"other 2.0.0 ({REGISTRY})")),
+    Pkg("serde", needs=("transitive",)),
+    Pkg("transitive"),
+    Pkg("twice", "1.0.0"),
+    Pkg("twice", "2.0.0"),
+    Pkg("other", "2.0.0"),
+)
+
+
+def test_a_lock_closed_over_its_own_dependencies_is_clean(
+    tmp_path: Path, cargo_accepts: list[list[str]]
+) -> None:
+    manifest = '[package]\nname = "app"\nversion = "0.1.0"\n\n[dependencies]\nserde = "1"\n'
+    verdict = stale_lock(tmp_path, {"Cargo.toml": manifest}, lock_text(CLOSED))
+    assert verdict.outcome is Outcome.CLEAN, verdict.render()
+
+
+@pytest.mark.parametrize(
+    ("removed", "listed"),
+    [
+        pytest.param("transitive", "transitive", id="a transitive package removed"),
+        pytest.param("other", f"other 2.0.0 ({REGISTRY})", id="a package named with its source removed"),
+    ],
+)
+def test_a_package_the_lock_lists_as_a_dependency_but_does_not_hold_is_reported(
+    tmp_path: Path, cargo_accepts: list[list[str]], removed: str, listed: str
+) -> None:
+    manifest = '[package]\nname = "app"\nversion = "0.1.0"\n\n[dependencies]\nserde = "1"\n'
+    body = lock_text(tuple(p for p in CLOSED if p.name != removed))
+    verdict = stale_lock(tmp_path, {"Cargo.toml": manifest}, body)
+    [message] = messages(verdict)
+    assert message.startswith(f"backend/Cargo.lock lists dependency '{listed}' of package '")
+    assert message.endswith("but has no such package")
+
+
+def test_a_dependency_naming_a_version_the_lock_does_not_hold_is_reported(
+    tmp_path: Path, cargo_accepts: list[list[str]]
+) -> None:
+    manifest = '[package]\nname = "app"\nversion = "0.1.0"\n\n[dependencies]\nserde = "1"\n'
+    body = lock_text(tuple(p for p in CLOSED if (p.name, p.version) != ("twice", "1.0.0")))
+    verdict = stale_lock(tmp_path, {"Cargo.toml": manifest}, body)
+    assert messages(verdict) == [
+        "backend/Cargo.lock lists dependency 'twice 1.0.0' of package 'app' 0.1.0 but has no such package"
+    ]
+
+
+def test_a_missing_package_listed_by_two_dependents_is_reported_once(
+    tmp_path: Path, cargo_accepts: list[list[str]]
+) -> None:
+    manifest = '[package]\nname = "app"\nversion = "0.1.0"\n\n[dependencies]\nserde = "1"\n'
+    packages = (
+        Pkg("app", "0.1.0", path=True, needs=("serde", "other")),
+        Pkg("serde", needs=("ghost",)),
+        Pkg("other", needs=("ghost",)),
+    )
+    verdict = stale_lock(tmp_path, {"Cargo.toml": manifest}, lock_text(packages))
+    assert len(messages(verdict)) == 1, messages(verdict)
+    assert "lists dependency 'ghost'" in messages(verdict)[0]
+
+
+def test_a_dependencies_entry_that_is_not_a_list_of_strings_is_reported(
+    tmp_path: Path, cargo_accepts: list[list[str]]
+) -> None:
+    body = HEADER + 'version = 3\n\n[[package]]\nname = "app"\nversion = "0.1.0"\ndependencies = "serde"\n'
+    verdict = stale_lock(tmp_path, SINGLE.files, body)
+    assert messages(verdict) == [
+        "backend/Cargo.lock has a [[package]] entry (number 1) whose `dependencies` is not a list of strings"
+    ]
+
+
+# --------------------------------------------------------------------- good locks pass
+
+
+@pytest.mark.parametrize("shape", SHAPES)
+def test_a_lock_that_satisfies_the_manifests_is_clean(
+    tmp_path: Path, cargo_accepts: list[list[str]], shape: Shape
+) -> None:
+    verdict = stale_lock(tmp_path, shape.files, shape.lock())
+    assert verdict.outcome is Outcome.CLEAN, verdict.render()
+    assert verdict.findings == ()
+
+
+@requires_cargo
+@pytest.mark.parametrize("shape", SHAPES)
+def test_a_lock_that_satisfies_the_manifests_is_clean_with_the_real_cargo_command(
+    tmp_path: Path, shape: Shape
+) -> None:
+    verdict = stale_lock(tmp_path, shape.files, shape.lock())
+    assert verdict.outcome is Outcome.CLEAN, verdict.render()
+
+
+# -------------------------------------------------- a direct dependency missing is found
+
+
+@pytest.mark.parametrize(("name", "key", "section"), SINGLE_DEPENDENCIES)
+def test_a_direct_dependency_missing_from_the_lock_is_reported(
+    tmp_path: Path, cargo_accepts: list[list[str]], name: str, key: str, section: str
+) -> None:
+    verdict = stale_lock(tmp_path, SINGLE.files, SINGLE.lock(drop=(name,)))
+    assert verdict.outcome is Outcome.FINDINGS, verdict.render()
+    assert messages(verdict) == [
+        f"backend/Cargo.lock lists no package '{name}' "
+        f"(dependency '{key}' in {section} of backend/Cargo.toml)"
+    ]
+
+
+@requires_cargo
+@pytest.mark.parametrize(("name", "key", "section"), SINGLE_DEPENDENCIES)
+def test_a_direct_dependency_missing_from_the_lock_is_reported_with_the_real_cargo_command(
+    tmp_path: Path, name: str, key: str, section: str
+) -> None:
+    verdict = stale_lock(tmp_path, SINGLE.files, SINGLE.lock(drop=(name,)))
+    assert [f.rule for f in verdict.findings] == ["LCK-002"], verdict.render()
+    assert f"lists no package '{name}'" in verdict.findings[0].message
+
+
+@pytest.mark.parametrize(("name", "key", "section"), SINGLE_DEPENDENCIES)
+def test_a_dependency_the_lock_holds_only_for_someone_else_is_reported(
+    tmp_path: Path, cargo_accepts: list[list[str]], name: str, key: str, section: str
+) -> None:
+    """The commonest stale lock: a manifest gains a dependency that is already in the lock because
+    another package brings it (`tokio`, `serde`). The package is in the lock; the MEMBER's own entry
+    does not list it, so `cargo build --locked` would refuse the lock. Presence anywhere is not enough."""
+    app, *rest = SINGLE.packages
+    app = app._replace(needs=tuple(n for n in app.needs if n != name))
+    carrier = Pkg("carrier", needs=(name,))
+    verdict = stale_lock(tmp_path, SINGLE.files, lock_text((app, *rest, carrier)))
+    assert messages(verdict) == [
+        f"backend/Cargo.lock package 'app' 0.1.0 does not list '{name}' as a dependency "
+        f"({section} of backend/Cargo.toml declares dependency '{key}')"
+    ]
+
+
+def test_a_workspace_member_whose_entry_lacks_an_inherited_dependency_is_reported(
+    tmp_path: Path, cargo_accepts: list[list[str]]
+) -> None:
+    web = next(p for p in VIRTUAL.packages if p.name == "web")
+    packages = tuple(
+        p._replace(needs=tuple(n for n in p.needs if n != "serde")) if p is web else p
+        for p in VIRTUAL.packages
+    )
+    packages = (*packages, Pkg("carrier", needs=("serde",)))
+    verdict = stale_lock(tmp_path, VIRTUAL.files, lock_text(packages))
+    assert messages(verdict) == [
+        "backend/Cargo.lock package 'web' 0.1.0 does not list 'serde' as a dependency "
+        "([dependencies] of backend/crates/web/Cargo.toml declares dependency 'serde')"
+    ]
+
+
+def test_a_dependency_listed_with_its_version_is_found_by_name(
+    tmp_path: Path, cargo_accepts: list[list[str]]
+) -> None:
+    """cargo writes `name version` when two versions of a crate are locked."""
+    app, *rest = SINGLE.packages
+    app = app._replace(needs=tuple("serde 1.0.0" if n == "serde" else n for n in app.needs))
+    packages = (app, *rest, Pkg("serde", "2.0.0"))
+    verdict = stale_lock(tmp_path, SINGLE.files, lock_text(packages))
+    assert verdict.outcome is Outcome.CLEAN, verdict.render()
+
+
+def test_a_package_that_dev_depends_on_itself_is_not_asked_to_list_itself(
+    tmp_path: Path, cargo_accepts: list[list[str]]
+) -> None:
+    manifest = (
+        '[package]\nname = "app"\nversion = "0.1.0"\n\n[features]\nextra = []\n\n'
+        '[dev-dependencies]\napp = { path = ".", features = ["extra"] }\n'
+    )
+    verdict = stale_lock(
+        tmp_path, {"Cargo.toml": manifest}, lock_text((Pkg("app", "0.1.0", path=True),))
+    )
+    assert verdict.outcome is Outcome.CLEAN, verdict.render()
+
+
+def test_a_renamed_dependency_is_judged_by_its_real_name_not_its_key(
+    tmp_path: Path, cargo_accepts: list[list[str]]
+) -> None:
+    """`sj = { package = "serde_json_fork" }`: a lock listing a package called `sj` is NOT
+    the dependency, and one listing `serde_json_fork` is, with no `sj` anywhere."""
+    wrong = SINGLE.lock(drop=("serde_json_fork",)) + Pkg("sj").text()
+    verdict = stale_lock(tmp_path, SINGLE.files, wrong)
+    assert [m.split(" (")[0] for m in messages(verdict)] == [
+        "backend/Cargo.lock lists no package 'serde_json_fork'"
+    ]
+
+
+def test_a_dependency_declared_as_its_own_table_is_judged(
+    tmp_path: Path, cargo_accepts: list[list[str]]
+) -> None:
+    manifest = (
+        '[package]\nname = "app"\nversion = "0.1.0"\n\n'
+        '[dependencies.tokio]\nversion = "1"\nfeatures = ["rt"]\n\n'
+        '[dev_dependencies]\nmockito = "1"\n\n'
+        '[build_dependencies]\nprost-build = "0.12"\n'
+    )
+    packages = (
+        Pkg("app", "0.1.0", path=True, needs=("tokio", "mockito", "prost-build")),
+        Pkg("tokio"),
+        Pkg("mockito"),
+        Pkg("prost-build"),
+    )
+    clean = stale_lock(tmp_path, {"Cargo.toml": manifest}, lock_text(packages))
+    assert clean.outcome is Outcome.CLEAN, clean.render()
+    gone = grade_without(tmp_path, packages, "tokio")
+    assert [m.split(" (")[0] for m in messages(gone)] == ["backend/Cargo.lock lists no package 'tokio'"]
+    gone = grade_without(tmp_path, packages, "mockito")
+    assert "in [dev_dependencies] of backend/Cargo.toml" in messages(gone)[0]
+    gone = grade_without(tmp_path, packages, "prost-build")
+    assert "in [build_dependencies] of backend/Cargo.toml" in messages(gone)[0]
+
+
+def grade_without(root: Path, packages: tuple[Pkg, ...], name: str) -> Verdict:
+    (root / "backend" / "Cargo.lock").write_text(lock_text(without(packages, name)), encoding="utf-8")
+    return grade(root)
+
+
+def test_a_dependency_both_members_need_is_reported_once(
+    tmp_path: Path, cargo_accepts: list[list[str]]
+) -> None:
+    files = {
+        **VIRTUAL.files,
+        "crates/api/Cargo.toml": '[package]\nname = "api"\nversion = "0.1.0"\n\n[dependencies]\nserde.workspace = true\n',
+    }
+    packages = (*VIRTUAL.packages, Pkg("api", "0.1.0", path=True, needs=("serde",)))
+    body = lock_text(without(packages, "serde"))
+    verdict = stale_lock(tmp_path, files, body)
+    assert len(messages(verdict)) == 1, messages(verdict)
+    assert messages(verdict)[0].startswith("backend/Cargo.lock lists no package 'serde' (dependency 'serde' in [dependencies] of ")
+
+
+# ------------------------------------------------------------ a workspace member missing
+
+
+def test_the_root_package_missing_from_the_lock_is_reported(
+    tmp_path: Path, cargo_accepts: list[list[str]]
+) -> None:
+    verdict = stale_lock(tmp_path, SINGLE.files, SINGLE.lock(drop=("app",)))
+    assert messages(verdict) == [
+        "backend/Cargo.lock lists no path package 'app' (workspace member backend/Cargo.toml)"
+    ]
+
+
+def test_a_member_whose_version_differs_is_reported(
+    tmp_path: Path, cargo_accepts: list[list[str]]
+) -> None:
+    verdict = stale_lock(tmp_path, SINGLE.files, SINGLE.lock(swap={"app": Pkg("app", "0.0.9", path=True)}))
+    assert messages(verdict) == [
+        "backend/Cargo.lock lists 'app' at version 0.0.9 but workspace member "
+        "backend/Cargo.toml declares 0.1.0"
+    ]
+
+
+def test_a_registry_package_of_the_same_name_does_not_satisfy_a_member(
+    tmp_path: Path, cargo_accepts: list[list[str]]
+) -> None:
+    """A member is a path package; a crates.io `app 0.1.0` in the lock is somebody else's."""
+    verdict = stale_lock(tmp_path, SINGLE.files, SINGLE.lock(swap={"app": Pkg("app", "0.1.0")}))
+    assert messages(verdict) == [
+        "backend/Cargo.lock lists no path package 'app' (workspace member backend/Cargo.toml)"
+    ]
+
+
+@pytest.mark.parametrize("member", ["web", "core-lib"])
+def test_a_virtual_workspace_member_missing_from_the_lock_is_reported(
+    tmp_path: Path, cargo_accepts: list[list[str]], member: str
+) -> None:
+    """One finding: `core-lib` is also a path dependency of `web`, and is reported once, as the member."""
+    verdict = stale_lock(tmp_path, VIRTUAL.files, VIRTUAL.lock(drop=(member,)))
+    assert verdict.outcome is Outcome.FINDINGS, verdict.render()
+    assert messages(verdict) == [
+        f"backend/Cargo.lock lists no path package '{member}' "
+        f"(workspace member backend/crates/{member}/Cargo.toml)"
+    ]
+
+
+def test_a_member_version_inherited_from_the_workspace_is_the_one_compared(
+    tmp_path: Path, cargo_accepts: list[list[str]]
+) -> None:
+    """`version.workspace = true` reads `[workspace.package].version` (0.3.0)."""
+    verdict = stale_lock(
+        tmp_path, VIRTUAL.files, VIRTUAL.lock(swap={"core-lib": Pkg("core-lib", "0.2.0", path=True)})
+    )
+    assert messages(verdict) == [
+        "backend/Cargo.lock lists 'core-lib' at version 0.2.0 but workspace member "
+        "backend/crates/core-lib/Cargo.toml declares 0.3.0"
+    ]
+
+
+def test_a_member_with_no_version_is_locked_at_0_0_0(
+    tmp_path: Path, cargo_accepts: list[list[str]]
+) -> None:
+    files = {"Cargo.toml": '[package]\nname = "app"\nedition = "2021"\n'}
+    clean = stale_lock(tmp_path, files, lock_text((Pkg("app", "0.0.0", path=True),)))
+    assert clean.outcome is Outcome.CLEAN, clean.render()
+    wrong = stale_lock(tmp_path, files, lock_text((Pkg("app", "0.1.0", path=True),)))
+    assert "declares 0.0.0" in messages(wrong)[0]
+
+
+# --------------------------------------------------- members, glob, exclude, inheritance
+
+
+def test_the_excluded_member_is_not_required_and_removing_the_exclude_requires_it(
+    tmp_path: Path, cargo_accepts: list[list[str]]
+) -> None:
+    """Negative control for `exclude`: `skipped` (and its `only-skipped` dependency) are in no
+    lock above and the gate is clean; take the `exclude` away and `skipped` becomes a member."""
+    clean = stale_lock(tmp_path, VIRTUAL.files, VIRTUAL.lock())
+    assert clean.outcome is Outcome.CLEAN, clean.render()
+
+    unexcluded = {
+        **VIRTUAL.files,
+        "Cargo.toml": VIRTUAL.files["Cargo.toml"].replace('exclude = ["crates/skipped"]\n', ""),
+    }
+    verdict = stale_lock(tmp_path, unexcluded, VIRTUAL.lock())
+    found = messages(verdict)
+    assert any("lists no path package 'skipped'" in m for m in found), found
+    assert any("lists no package 'only-skipped'" in m for m in found), found
+
+
+def test_a_workspace_dependency_no_member_uses_is_not_required(
+    tmp_path: Path, cargo_accepts: list[list[str]]
+) -> None:
+    """`[workspace.dependencies] unused = "1"`: cargo locks only what a member uses."""
+    assert "unused" in VIRTUAL.files["Cargo.toml"]
+    verdict = stale_lock(tmp_path, VIRTUAL.files, VIRTUAL.lock())
+    assert verdict.outcome is Outcome.CLEAN, verdict.render()
+
+
+@pytest.mark.parametrize(
+    ("name", "key", "section"),
+    [
+        pytest.param("serde", "serde", "[dependencies]", id="inherited via workspace = true"),
+        pytest.param("real_name", "renamed", "[dependencies]", id="inherited, renamed, optional"),
+        pytest.param("log", "log", "[dev-dependencies]", id="inherited dev"),
+    ],
+)
+def test_an_inherited_dependency_missing_from_the_lock_is_reported(
+    tmp_path: Path, cargo_accepts: list[list[str]], name: str, key: str, section: str
+) -> None:
+    verdict = stale_lock(tmp_path, VIRTUAL.files, VIRTUAL.lock(drop=(name,)))
+    assert messages(verdict) == [
+        f"backend/Cargo.lock lists no package '{name}' (dependency '{key}' in {section} of "
+        "backend/crates/web/Cargo.toml)"
+    ]
+
+
+def test_members_listed_without_a_glob_are_judged(
+    tmp_path: Path, cargo_accepts: list[list[str]]
+) -> None:
+    files = {
+        **VIRTUAL.files,
+        "Cargo.toml": VIRTUAL.files["Cargo.toml"].replace(
+            'members = ["crates/*"]', 'members = ["crates/web", "crates/core-lib"]'
+        ),
+    }
+    clean = stale_lock(tmp_path, files, VIRTUAL.lock())
+    assert clean.outcome is Outcome.CLEAN, clean.render()
+    gone = stale_lock(tmp_path, files, VIRTUAL.lock(drop=("web",)))
+    assert any("lists no path package 'web'" in m for m in messages(gone))
+
+
+def test_a_hidden_directory_matched_by_a_glob_is_a_member(
+    tmp_path: Path, cargo_accepts: list[list[str]]
+) -> None:
+    """Rust's `glob` crate (what cargo expands `members` with) has
+    `require_literal_leading_dot = false` by default: `crates/*` matches `crates/.tools`."""
+    files = {
+        **VIRTUAL.files,
+        "crates/.tools/Cargo.toml": '[package]\nname = "tools"\nversion = "0.1.0"\n',
+    }
+    verdict = stale_lock(tmp_path, files, VIRTUAL.lock())
+    assert any("lists no path package 'tools'" in m for m in messages(verdict)), messages(verdict)
+
+
+# ------------------------------------------------------------------------- path dependencies
+
+
+@pytest.mark.parametrize(
+    ("missing", "expected"),
+    [
+        pytest.param("helper-dep", "lists no package 'helper-dep' (dependency 'helper-dep' in [dependencies] of backend/helper/Cargo.toml)", id="dependency of an implicit member"),
+        pytest.param("helper", "lists no path package 'helper'", id="the implicit member itself, under its real name"),
+        pytest.param("shared", "lists no path package 'shared' (dependency 'shared' in [dependencies] of backend/member-a/Cargo.toml)", id="path dependency outside the workspace root"),
+    ],
+)
+def test_path_dependencies_are_judged_by_the_name_in_their_own_manifest(
+    tmp_path: Path, cargo_accepts: list[list[str]], missing: str, expected: str
+) -> None:
+    """`h = { path = "helper", package = "helper" }` and `shared = { path = "../../shared" }`:
+    the lock names the package its manifest declares. `helper` lives inside the workspace root
+    and is in no `members` list, so cargo makes it a member and locks its dependencies."""
+    verdict = stale_lock(tmp_path, IMPLICIT.files, IMPLICIT.lock(drop=(missing,)))
+    assert any(expected in m for m in messages(verdict)), messages(verdict)
+
+
+def test_a_path_dependency_keyed_differently_from_its_package_is_judged_by_the_package(
+    tmp_path: Path, cargo_accepts: list[list[str]]
+) -> None:
+    files = {
+        "Cargo.toml": '[package]\nname = "app"\nversion = "0.1.0"\n\n[dependencies]\nalias = { path = "real" }\n',
+        "real/Cargo.toml": '[package]\nname = "real-name"\nversion = "0.7.0"\n',
+    }
+    good = (Pkg("app", "0.1.0", path=True, needs=("real-name",)), Pkg("real-name", "0.7.0", path=True))
+    clean = stale_lock(tmp_path, files, lock_text(good))
+    assert clean.outcome is Outcome.CLEAN, clean.render()
+    keyed = (Pkg("app", "0.1.0", path=True, needs=("alias",)), Pkg("alias", "0.7.0", path=True))
+    wrong = stale_lock(tmp_path, files, lock_text(keyed))
+    assert [m.split(" (")[0] for m in messages(wrong)] == ["backend/Cargo.lock lists no path package 'real-name'"]
+
+
+def test_a_registry_package_does_not_satisfy_an_implicit_member(
+    tmp_path: Path, cargo_accepts: list[list[str]]
+) -> None:
+    verdict = stale_lock(
+        tmp_path, IMPLICIT.files, IMPLICIT.lock(swap={"helper": Pkg("helper", "0.4.0")})
+    )
+    assert any("lists no path package 'helper'" in m for m in messages(verdict)), messages(verdict)
+
+
+def test_a_registry_package_does_not_satisfy_a_path_dependency_outside_the_workspace(
+    tmp_path: Path, cargo_accepts: list[list[str]]
+) -> None:
+    """`shared` is a path dependency and no member: only the dependency check can notice that the
+    lock holds a crates.io `shared 0.5.0` instead of the path package."""
+    verdict = stale_lock(
+        tmp_path, IMPLICIT.files, IMPLICIT.lock(swap={"shared": Pkg("shared", "0.5.0")})
+    )
+    assert messages(verdict) == [
+        "backend/Cargo.lock lists no path package 'shared' (dependency 'shared' in "
+        "[dependencies] of backend/member-a/Cargo.toml)"
+    ]
+
+
+# --------------------------------------------------------- what the check cannot judge
+
+
+UNJUDGEABLE = [
+    pytest.param(
+        {"Cargo.toml": '[package]\nname = "app"\nversion = "0.1.0"\n\n[dependencies]\nfoo = 3\n'},
+        ["'foo'", "backend/Cargo.toml", "[dependencies]"],
+        id="dependency spec that is neither a string nor a table",
+    ),
+    pytest.param(
+        {"Cargo.toml": '[package]\nname = "app"\nversion = "0.1.0"\n\n[dependencies]\nfoo = { workspace = false }\n'},
+        ["'foo'", "workspace = false"],
+        id="workspace = false",
+    ),
+    pytest.param(
+        {"Cargo.toml": '[package]\nname = "app"\nversion = "0.1.0"\n\n[dependencies]\nfoo = { workspace = true }\n'},
+        ["'foo'", "[workspace.dependencies]"],
+        id="workspace = true without a [workspace.dependencies] entry",
+    ),
+    pytest.param(
+        {"Cargo.toml": '[package]\nname = "app"\nversion = "0.1.0"\n\n[dependencies]\nfoo = { path = "nowhere" }\n'},
+        ["'foo'", "nowhere"],
+        id="path dependency whose manifest is not there",
+    ),
+    pytest.param(
+        {"Cargo.toml": '[package]\nname = "app"\nversion = "0.1.0"\n\n[target.\'cfg(unix)\'.dev-dependencies]\nbar = [1]\n'},
+        ["'bar'", "[target.'cfg(unix)'.dev-dependencies]"],
+        id="target-specific dependency spec that is a list",
+    ),
+    pytest.param(
+        {"Cargo.toml": 'dependencies = 3\n\n[package]\nname = "app"\nversion = "0.1.0"\n'},
+        ["[dependencies]", "backend/Cargo.toml", "not a table"],
+        id="a dependency section that is not a table",
+    ),
+    pytest.param(
+        {"Cargo.toml": '[workspace]\nmembers = ["crates/none-*"]\n'},
+        ["crates/none-*", "matches no directory"],
+        id="members entry that matches nothing",
+    ),
+    pytest.param(
+        {"Cargo.toml": '[workspace]\nmembers = ["crates/a"]\n', "crates/a/readme.txt": "no manifest here\n"},
+        ["crates/a", "no Cargo.toml"],
+        id="member directory without a Cargo.toml",
+    ),
+    pytest.param(
+        {"Cargo.toml": '[workspace]\nmembers = ["crates/*"]\nexclude = ["crates/g*"]\n', "crates/a/Cargo.toml": '[package]\nname = "a"\nversion = "0.1.0"\n'},
+        ["exclude", "crates/g*"],
+        id="exclude entry with glob syntax",
+    ),
+    pytest.param(
+        {"Cargo.toml": '[package]\nname = "app"\nversion = "0.1.0"\n[dependencies\n'},
+        ["backend/Cargo.toml", "not valid TOML"],
+        id="manifest that is not TOML",
+    ),
+    pytest.param(
+        {"Cargo.toml": '[profile.release]\nlto = true\n'},
+        ["backend/Cargo.toml", "[package]", "[workspace]"],
+        id="manifest with neither [package] nor [workspace]",
+    ),
+    pytest.param(
+        {"Cargo.toml": '[workspace]\nmembers = ["crates/a"]\n', "crates/a/Cargo.toml": '[workspace]\nmembers = []\n'},
+        ["crates/a/Cargo.toml", "[package]"],
+        id="a member that is not a package",
+    ),
+    pytest.param(
+        {"Cargo.toml": '[package]\nname = "app"\nversion = 5\n'},
+        ["backend/Cargo.toml", "version"],
+        id="package version that is not a string",
+    ),
+]
+
+
+@pytest.mark.parametrize(("files", "named"), UNJUDGEABLE)
+def test_what_the_manifests_text_cannot_judge_is_could_not_run_naming_it(
+    tmp_path: Path, cargo_accepts: list[list[str]], files: dict[str, str], named: list[str]
+) -> None:
+    """Never skipped, never a pass: the lock below is fine, and the verdict is still could-not-run."""
+    verdict = stale_lock(tmp_path, files, lock_text((Pkg("app", "0.1.0", path=True), Pkg("a", "0.1.0", path=True))))
+    assert verdict.outcome is Outcome.COULD_NOT_RUN, verdict.render()
+    assert verdict.findings == ()
+    for fragment in named:
+        assert fragment in verdict.message, (fragment, verdict.message)
+
+
+def test_a_garbage_lock_is_reported_even_when_the_manifests_cannot_be_judged(
+    tmp_path: Path, cargo_accepts: list[list[str]]
+) -> None:
+    """The lock alone is conclusive: it need not be compared with anything."""
+    verdict = stale_lock(tmp_path, {"Cargo.toml": "[profile.release]\n"}, "version = 99\n")
+    assert verdict.outcome is Outcome.FINDINGS, verdict.render()
+
+
+# ----------------------------------------------- the finding's wording, remedy and modes
+
+
+def test_the_finding_wording_and_remedy(tmp_path: Path, cargo_accepts: list[list[str]]) -> None:
+    verdict = stale_lock(tmp_path, SINGLE.files, SINGLE.lock(drop=("serde",)))
+    [finding] = verdict.findings
+    assert finding.rule == "LCK-002"
+    assert finding.path == "backend/Cargo.lock"
+    assert finding.message == (
+        "backend/Cargo.lock lists no package 'serde' (dependency 'serde' in [dependencies] of backend/Cargo.toml)"
+    )
+    assert finding.fix == FIX
+
+
+def test_the_remedy_is_the_one_a_cargo_rejection_has(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """One remedy for every LCK-002 message, cargo's own rejection included."""
+    monkeypatch.setattr(module.shutil, "which", lambda name: "/fake/cargo")
+    monkeypatch.setattr(
+        module.subprocess,
+        "run",
+        lambda argv, **_: SimpleNamespace(returncode=0 if argv[1] == "--version" else 101),
+    )
+    verdict = stale_lock(tmp_path, SINGLE.files, SINGLE.lock())
+    [finding] = verdict.findings
+    assert finding.message == "backend/Cargo.lock does not satisfy backend/Cargo.toml"
+    assert finding.fix == FIX
+
+
+def test_a_cargo_rejection_is_the_only_finding_for_that_lock(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """The early-return shape: a manifest cargo refuses is one finding. A garbage lock beside
+    it is not reported on top (cargo is the authority on the manifest, and the lock cannot be
+    compared with a manifest cargo did not accept)."""
+    calls: list[list[str]] = []
+
+    def fake_run(argv: list[str], **_: object) -> object:
+        calls.append(argv)
+        return SimpleNamespace(returncode=0 if argv[1] == "--version" else 101)
+
+    monkeypatch.setattr(module.shutil, "which", lambda name: "/fake/cargo")
+    monkeypatch.setattr(module.subprocess, "run", fake_run)
+    verdict = stale_lock(tmp_path, SINGLE.files, "this is [[ not a lockfile\n")
+    assert messages(verdict) == ["backend/Cargo.lock does not satisfy backend/Cargo.toml"]
+    assert [argv[:2] for argv in calls] == [["cargo", "--version"], ["cargo", "metadata"]]
+
+
+def test_the_undeclared_mode_grades_the_tree_default_lockfile(
+    tmp_path: Path, cargo_accepts: list[list[str]]
+) -> None:
+    verdict = stale_lock(tmp_path, SINGLE.files, "version = 99\n")
+    assert {f.path for f in verdict.findings} == {"backend/Cargo.lock"}
+    assert {f.fix for f in verdict.findings} == {FIX}
+
+
+DECLARED = {"cargo-manifests": "nested/*/Cargo.toml", "cargo-lockfiles": "nested/ws/Cargo.lock"}
+
+
+def test_the_declared_mode_grades_the_declared_lockfile_in_its_own_directory(
+    tmp_path: Path, cargo_accepts: list[list[str]]
+) -> None:
+    lay(tmp_path, SINGLE.files, SINGLE.lock(drop=("cc",)), where="nested/ws")
+    verdict = grade(tmp_path, declarations=DECLARED)
+    [finding] = verdict.findings
+    assert finding.rule == "LCK-002"
+    assert finding.path == "nested/ws/Cargo.lock"
+    assert finding.message == (
+        "nested/ws/Cargo.lock lists no package 'cc' "
+        "(dependency 'cc' in [build-dependencies] of nested/ws/Cargo.toml)"
+    )
+    assert finding.fix == (
+        "run: (cd nested/ws && cargo update) to resync nested/ws/Cargo.lock with "
+        "nested/ws/Cargo.toml, then commit the result"
+    )
+
+
+def test_the_declared_mode_is_clean_for_a_good_lock(
+    tmp_path: Path, cargo_accepts: list[list[str]]
+) -> None:
+    lay(tmp_path, SINGLE.files, SINGLE.lock(), where="nested/ws")
+    verdict = grade(tmp_path, declarations=DECLARED)
+    assert verdict.outcome is Outcome.CLEAN, verdict.render()
+
+
+def test_every_declared_lockfile_is_judged_and_each_stale_one_is_reported(
+    tmp_path: Path, cargo_accepts: list[list[str]]
+) -> None:
+    lay(tmp_path, SINGLE.files, SINGLE.lock(drop=("cc",)), where="nested/a")
+    lay(tmp_path, SINGLE.files, SINGLE.lock(), where="nested/b")
+    lay(tmp_path, SINGLE.files, "version = 99\n", where="nested/c")
+    declarations = {
+        "cargo-manifests": "nested/*/Cargo.toml",
+        "cargo-lockfiles": "nested/a/Cargo.lock,nested/b/Cargo.lock,nested/c/Cargo.lock",
+    }
+    verdict = grade(tmp_path, declarations=declarations)
+    assert sorted({f.path for f in verdict.findings}) == ["nested/a/Cargo.lock", "nested/c/Cargo.lock"]
+
+
+# --------------------------------------------- determinism: cargo is asked only what it was
+
+
+def test_cargo_is_asked_exactly_the_two_questions_it_always_was(
+    tmp_path: Path, cargo_accepts: list[list[str]]
+) -> None:
+    """The content validation spawns nothing and never drops `--no-deps`: the verdict cannot
+    depend on the machine's registry cache or network."""
+    stale_lock(tmp_path, VIRTUAL.files, VIRTUAL.lock(drop=("serde",)))
+    assert [argv[:2] for argv in cargo_accepts] == [["cargo", "--version"], ["cargo", "metadata"]]
+    metadata = cargo_accepts[1]
+    for flag in ("--locked", "--offline", "--no-deps"):
+        assert flag in metadata
+    assert metadata[metadata.index("--manifest-path") + 1] == str(tmp_path / "backend" / "Cargo.toml")
+
+
+def test_without_cargo_the_gate_is_still_could_not_run(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """The cargo guard is kept: a stale lock does not turn into a verdict on a machine without cargo."""
+    monkeypatch.setattr(module.shutil, "which", lambda name: None)
+    verdict = stale_lock(tmp_path, SINGLE.files, "version = 99\n")
+    assert verdict.outcome is Outcome.COULD_NOT_RUN, verdict.render()
+    assert "cargo is required" in verdict.message
+
+
+def test_the_missing_lockfile_is_still_lck_001_and_returns_first(
+    tmp_path: Path, cargo_accepts: list[list[str]]
+) -> None:
+    lay(tmp_path, SINGLE.files, "version = 99\n")
+    (tmp_path / "backend" / "Cargo.lock").unlink()
+    verdict = grade(tmp_path)
+    [finding] = verdict.findings
+    assert (finding.rule, finding.message) == ("LCK-001", "missing backend/Cargo.lock")
+    assert cargo_accepts == []
+
+
+# ------------------------------------------------------------------- the documented limit
+
+
+def test_version_requirement_drift_is_not_detected_offline(
+    tmp_path: Path, cargo_accepts: list[list[str]]
+) -> None:
+    """A documented LIMIT, pinned so nobody mistakes it for coverage: the manifest asks for
+    `serde = "99"` and the lock holds `serde 1.0.0`. Presence, structure and membership are
+    checked offline; whether a locked VERSION still satisfies a manifest REQUIREMENT is
+    `cargo metadata` without `--no-deps`, which needs the registry. When that changes on
+    purpose, this test changes with it."""
+    manifest = '[package]\nname = "app"\nversion = "0.1.0"\n\n[dependencies]\nserde = "99"\n'
+    verdict = stale_lock(
+        tmp_path,
+        {"Cargo.toml": manifest},
+        lock_text((Pkg("app", "0.1.0", path=True, needs=("serde",)), Pkg("serde", "1.0.0"))),
+    )
+    assert verdict.outcome is Outcome.CLEAN, verdict.render()