build(cargo): add a check that aligned workspaces lock shared crates like the root

`cargo --locked` only checks a lockfile against its own manifest. A workspace
outside the root that builds root crates through path dependencies, such as the
testkit suites building `openshell-sdk`, has its own Cargo.lock, so the two
lockfiles can resolve a shared crate to different versions without any check
failing. That is how aws-lc-sys 0.46 was picked up in #4629, which does not link
against the AWS-LC that Nix provides.

check_cargo_lockfile_alignment.py fails when an aligned workspace locks a
registry crate that the root lockfile also contains at a version the root
lockfile does not have. With --fix it re-locks the workspace starting from the
root lockfile. tests/testkit is the first aligned workspace.

The script and its tests come from #4629 (a37ebe9).

Co-authored-by: Evan Lezar <elezar@nvidia.com>
Signed-off-by: Matthew Grossman <mgrossman@nvidia.com>

Author: matthewgrossman

tasks/scripts/check_cargo_lockfile_alignment.py

@@ -0,0 +1,171 @@
+#!/usr/bin/env python3
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+# /// script
+# requires-python = ">=3.11"
+# ///
+
+"""Check that aligned Cargo workspaces lock shared crates like the root does.
+
+Some workspaces outside the root build root crates through path
+dependencies, for example the testkit suites build `openshell-sdk`. Each
+workspace has its own Cargo.lock, and `cargo --locked` only checks a lockfile
+against its own manifest, so nothing stops the two lockfiles from resolving
+the same crate to different versions. The root's versions are the ones CI and
+the Nix toolchain are built for; a newer `aws-lc-sys`, for example, does not
+link against the AWS-LC that Nix provides.
+
+This check fails when an aligned workspace locks a registry crate that the
+root lockfile also contains at a version the root lockfile does not have.
+With `--fix`, it re-locks each aligned workspace starting from the root
+lockfile.
+"""
+
+from __future__ import annotations
+
+import argparse
+import re
+import shutil
+import subprocess
+import sys
+import tomllib
+from dataclasses import dataclass
+from pathlib import Path
+
+# Workspaces whose shared crates must match the root lockfile. Add a
+# workspace here once its lockfile has been aligned with `--fix`.
+ALIGNED_WORKSPACES = (
+    "tests/testkit",
+)
+
+
+@dataclass(frozen=True)
+class Mismatch:
+    workspace: str
+    name: str
+    version: str
+    root_versions: tuple[str, ...]
+
+    def target(self) -> str | None:
+        """The root version semver-compatible with the locked one, if any."""
+        key = compat_key(self.version)
+        candidates = [v for v in self.root_versions if compat_key(v) == key]
+        return max(candidates, key=version_tuple) if candidates else None
+
+
+def version_tuple(version: str) -> tuple[int, ...]:
+    core = re.split(r"[-+]", version, maxsplit=1)[0]
+    return tuple(int(part) for part in core.split("."))
+
+
+def compat_key(version: str) -> tuple[int, ...]:
+    """Cargo's caret-compatibility class: the leftmost non-zero component."""
+    major, minor, patch = (*version_tuple(version), 0, 0, 0)[:3]
+    if major:
+        return (major,)
+    if minor:
+        return (0, minor)
+    return (0, 0, patch)
+
+
+def registry_versions(lockfile: Path) -> dict[str, set[str]]:
+    """Versions of registry (non-path) packages in a lockfile, by name."""
+    data = tomllib.loads(lockfile.read_text())
+    versions: dict[str, set[str]] = {}
+    for package in data.get("package", []):
+        if "source" in package:
+            versions.setdefault(package["name"], set()).add(package["version"])
+    return versions
+
+
+def mismatches(root: Path, workspace: str) -> list[Mismatch]:
+    root_versions = registry_versions(root / "Cargo.lock")
+    found = []
+    for name, versions in sorted(
+        registry_versions(root / workspace / "Cargo.lock").items()
+    ):
+        shared = root_versions.get(name)
+        if shared is None:
+            continue
+        for version in sorted(versions - shared, key=version_tuple):
+            found.append(
+                Mismatch(
+                    workspace, name, version, tuple(sorted(shared, key=version_tuple))
+                )
+            )
+    return found
+
+
+def fix(root: Path, workspace: str) -> list[Mismatch]:
+    """Re-lock the workspace starting from the root lockfile.
+
+    Coupled crates such as the `futures-*` family pin each other, so they
+    cannot be moved one at a time. Seeding the workspace lockfile with the
+    root's lets Cargo keep every root version that still fits, add only the
+    crates the root does not have, and drop the rest. Returns what is still
+    misaligned afterwards.
+    """
+    shutil.copyfile(root / "Cargo.lock", root / workspace / "Cargo.lock")
+    subprocess.run(
+        [
+            "cargo",
+            "metadata",
+            "--format-version",
+            "1",
+            "--manifest-path",
+            str(root / workspace / "Cargo.toml"),
+        ],
+        check=True,
+        stdout=subprocess.DEVNULL,
+    )
+    return mismatches(root, workspace)
+
+
+def report(problems: list[Mismatch]) -> None:
+    for m in problems:
+        target = m.target()
+        hint = (
+            f"; root has {target}"
+            if target
+            else f"; root has {', '.join(m.root_versions)}"
+        )
+        print(
+            f"error: {m.workspace}: {m.name} {m.version} is not in the root Cargo.lock{hint}",
+            file=sys.stderr,
+        )
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    parser.add_argument(
+        "--fix", action="store_true", help="update aligned lockfiles to root versions"
+    )
+    args = parser.parse_args(argv)
+
+    root = Path(
+        subprocess.run(
+            ["git", "rev-parse", "--show-toplevel"],
+            check=True,
+            capture_output=True,
+            text=True,
+        ).stdout.strip()
+    )
+    problems: list[Mismatch] = []
+    for workspace in ALIGNED_WORKSPACES:
+        print(f"Checking {workspace}/Cargo.lock against Cargo.lock")
+        problems += fix(root, workspace) if args.fix else mismatches(root, workspace)
+
+    if problems:
+        report(problems)
+        if not args.fix:
+            print(
+                "Run `uv run tasks/scripts/check_cargo_lockfile_alignment.py --fix` to align them.",
+                file=sys.stderr,
+            )
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

tasks/scripts/check_cargo_lockfile_alignment_test.py

@@ -0,0 +1,85 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Tests for the Cargo lockfile alignment check."""
+
+from __future__ import annotations
+
+import importlib.util
+import sys
+from pathlib import Path
+
+_SPEC = importlib.util.spec_from_file_location(
+    "check_cargo_lockfile_alignment",
+    Path(__file__).with_name("check_cargo_lockfile_alignment.py"),
+)
+assert _SPEC and _SPEC.loader
+alignment = importlib.util.module_from_spec(_SPEC)
+sys.modules[_SPEC.name] = alignment
+_SPEC.loader.exec_module(alignment)
+
+REGISTRY = 'source = "registry+https://github.com/rust-lang/crates.io-index"'
+
+
+def lockfile(path: Path, packages: list[tuple[str, str, bool]]) -> None:
+    """Write a lockfile of (name, version, from_registry) packages."""
+    entries = []
+    for name, version, from_registry in packages:
+        entry = f'[[package]]\nname = "{name}"\nversion = "{version}"\n'
+        if from_registry:
+            entry += REGISTRY + "\n"
+        entries.append(entry)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text("version = 4\n\n" + "\n".join(entries))
+
+
+def test_compat_key_follows_cargo_caret_rules() -> None:
+    assert alignment.compat_key("1.52.1") == (1,)
+    assert alignment.compat_key("0.44.0") == (0, 44)
+    assert alignment.compat_key("0.0.3") == (0, 0, 3)
+    assert alignment.compat_key("1.0.4+wasi-0.2.12") == (1,)
+
+
+def test_reports_shared_registry_crates_at_other_versions(tmp_path: Path) -> None:
+    lockfile(
+        tmp_path / "Cargo.lock",
+        [
+            ("tokio", "1.52.1", True),
+            ("rand", "0.8.6", True),
+            ("rand", "0.9.4", True),
+            ("openshell-sdk", "0.0.0", False),
+        ],
+    )
+    lockfile(
+        tmp_path / "ws" / "Cargo.lock",
+        [
+            ("tokio", "1.53.1", True),
+            ("rand", "0.9.5", True),
+            ("rand", "0.8.6", True),
+            ("only-here", "2.0.0", True),
+            ("openshell-sdk", "0.0.0", False),
+        ],
+    )
+
+    found = alignment.mismatches(tmp_path, "ws")
+
+    assert [(m.name, m.version, m.target()) for m in found] == [
+        ("rand", "0.9.5", "0.9.4"),
+        ("tokio", "1.53.1", "1.52.1"),
+    ]
+
+
+def test_no_target_without_a_compatible_root_version(tmp_path: Path) -> None:
+    lockfile(tmp_path / "Cargo.lock", [("syn", "1.0.109", True)])
+    lockfile(tmp_path / "ws" / "Cargo.lock", [("syn", "2.0.119", True)])
+
+    (found,) = alignment.mismatches(tmp_path, "ws")
+
+    assert found.target() is None
+
+
+def test_aligned_lockfiles_pass(tmp_path: Path) -> None:
+    lockfile(tmp_path / "Cargo.lock", [("tokio", "1.52.1", True)])
+    lockfile(tmp_path / "ws" / "Cargo.lock", [("tokio", "1.52.1", True)])
+
+    assert alignment.mismatches(tmp_path, "ws") == []