Build AI methods with your coding agent, then run them anywhere: as an MCP for chatbots, as a webapp for people, or via API for your software.
"""Unit tests for the SHA-keyed method clone cache, against real local git repositories.
Everything runs on-disk (`file://` remotes) — no network. Pins the cache's contract: the
reference is resolved to its commit SHA by `ls-remote` before any clone (tags-only for
`@<tag>`), a cached SHA is never re-cloned, a moved tag resolves to a new SHA and a fresh
clone (never cache by tag alone), and the bounds evict oldest-first while keeping the newest
entry.
"""
import os
import subprocess
import time
from pathlib import Path
import pytest
from pipelex.errors.problem import ProblemView
from pipelex.methods.exceptions import MethodFetchError
from pipelex.methods.fetching import fetch_method_package
from pipelex.methods.method_ref import parse_method_ref
from pytest_mock import MockerFixture
from pipelex_api.method_cache import MethodCloneCache, resolve_remote_commit_sha
from tests.unit._constants import STUB_METHOD_MANIFEST, VALID_MTHDS
_REF = parse_method_ref("github.com/pipelex/methods/[email protected]")
_BARE_REF = parse_method_ref("github.com/pipelex/methods/documents")
def _git(*args: str, cwd: Path) -> str:
result = subprocess.run( # noqa: S603 — fixed argv against the test's own tmp repo
["git", "-c", "[email protected]", "-c", "user.name=Test", "-c", "commit.gpgsign=false", *args], # noqa: S607
cwd=cwd,
capture_output=True,
text=True,
check=True,
timeout=60,
)
return result.stdout.strip()
@pytest.fixture
def origin(tmp_path: Path) -> tuple[str, Path]:
"""A local origin repository holding the stub package, tagged `v0.1.0`; returns (clone_url, repo_dir)."""
repo = tmp_path / "origin"
package_dir = repo / "methods" / "documents"
package_dir.mkdir(parents=True)
(package_dir / "METHODS.toml").write_text(STUB_METHOD_MANIFEST, encoding="utf-8")
(package_dir / "documents.mthds").write_text(VALID_MTHDS, encoding="utf-8")
_git("init", "-b", "main", cwd=repo)
_git("add", "-A", cwd=repo)
_git("commit", "-m", "seed package", cwd=repo)
_git("tag", "-a", "v0.1.0", "-m", "first tag", cwd=repo)
return f"file://{repo}", repo
class TestMethodCloneCache:
def test_resolve_remote_commit_sha_for_tag_and_head(self, origin: tuple[str, Path]):
clone_url, repo = origin
head_sha = _git("rev-parse", "HEAD", cwd=repo)
# An annotated tag resolves to its PEELED commit SHA — the same value `rev-parse HEAD`
# reports inside a clone at that tag — not the tag object's own SHA.
assert resolve_remote_commit_sha(ref=_REF, clone_url=clone_url) == head_sha
# A bare reference resolves the default branch HEAD.
assert resolve_remote_commit_sha(ref=_BARE_REF, clone_url=clone_url) == head_sha
def test_branch_names_are_refused_as_tags(self, origin: tuple[str, Path]):
clone_url, _ = origin
branch_ref = parse_method_ref("github.com/pipelex/methods/documents@main")
with pytest.raises(MethodFetchError, match="does not name a git tag") as exc_info:
resolve_remote_commit_sha(ref=branch_ref, clone_url=clone_url)
assert exc_info.value.resolve_error_code() == "method.not_found"
# The caller reads which reference was refused, never the code's title alone.
problem = exc_info.value.to_problem(view=ProblemView.CALLER)
assert problem.to_wire()["params"] == {"method_ref": branch_ref.ref_str}
assert branch_ref.ref_str in problem.detail
def test_a_cached_sha_is_never_recloned(self, origin: tuple[str, Path], tmp_path: Path, mocker: MockerFixture):
clone_url, repo = origin
head_sha = _git("rev-parse", "HEAD", cwd=repo)
cache = MethodCloneCache(root_dir=tmp_path / "cache")
fetch_spy = mocker.spy(cache, "_package_from_clone")
clone_spy = mocker.patch("pipelex_api.method_cache.fetch_method_package", wraps=fetch_method_package)
with cache.pinned_package(ref=_REF, clone_url=clone_url) as first:
pass
with cache.pinned_package(ref=_REF, clone_url=clone_url) as second:
pass
assert clone_spy.call_count == 1, "the second request must be served from the cache"
assert fetch_spy.call_count == 2, "location + bounds re-run on every request"
assert first.commit_sha == head_sha
assert second.commit_sha == head_sha
assert first.package_dir == second.package_dir
assert (tmp_path / "cache" / head_sha).is_dir()
# Provenance is the honest record: address, tag, and the resolved SHA.
assert first.provenance.address == "github.com/pipelex/methods/documents"
assert first.provenance.tag == "v0.1.0"
def test_a_moved_tag_resolves_to_a_fresh_clone(self, origin: tuple[str, Path], tmp_path: Path):
clone_url, repo = origin
cache = MethodCloneCache(root_dir=tmp_path / "cache")
with cache.pinned_package(ref=_REF, clone_url=clone_url) as first:
pass
# Move the tag: a new commit, and v0.1.0 forced onto it. Never cache by tag alone —
# the same reference must now fetch the NEW commit.
(repo / "methods" / "documents" / "extra.mthds").write_text(VALID_MTHDS.replace('"smoke"', '"extra"'), encoding="utf-8")
_git("add", "-A", cwd=repo)
_git("commit", "-m", "move the tag", cwd=repo)
_git("tag", "-f", "-a", "v0.1.0", "-m", "moved tag", cwd=repo)
with cache.pinned_package(ref=_REF, clone_url=clone_url) as second:
pass
assert second.commit_sha != first.commit_sha
assert (tmp_path / "cache" / first.commit_sha).is_dir()
assert (tmp_path / "cache" / second.commit_sha).is_dir()
def test_count_bound_evicts_oldest_keeping_newest(self, origin: tuple[str, Path], tmp_path: Path, mocker: MockerFixture):
clone_url, repo = origin
mocker.patch("pipelex_api.method_cache.MAX_METHOD_CACHE_CLONES", 1)
cache = MethodCloneCache(root_dir=tmp_path / "cache")
with cache.pinned_package(ref=_REF, clone_url=clone_url) as first:
pass
(repo / "methods" / "documents" / "extra.mthds").write_text(VALID_MTHDS.replace('"smoke"', '"extra"'), encoding="utf-8")
_git("add", "-A", cwd=repo)
_git("commit", "-m", "second version", cwd=repo)
_git("tag", "-a", "v0.2.0", "-m", "second tag", cwd=repo)
# Make the first entry visibly older than the newcomer (mtime is the eviction order).
old = time.time() - 120
os.utime(tmp_path / "cache" / first.commit_sha, (old, old))
second_ref = parse_method_ref("github.com/pipelex/methods/[email protected]")
with cache.pinned_package(ref=second_ref, clone_url=clone_url) as second:
pass
assert not (tmp_path / "cache" / first.commit_sha).exists(), "the oldest entry is evicted past the count bound"
assert (tmp_path / "cache" / second.commit_sha).is_dir(), "the newest entry always survives"
def test_age_bound_evicts_stale_entries(self, origin: tuple[str, Path], tmp_path: Path, mocker: MockerFixture):
clone_url, repo = origin
mocker.patch("pipelex_api.method_cache.MAX_METHOD_CACHE_AGE_SECONDS", 3600)
cache = MethodCloneCache(root_dir=tmp_path / "cache")
with cache.pinned_package(ref=_REF, clone_url=clone_url) as first:
pass
stale = time.time() - 7200
os.utime(tmp_path / "cache" / first.commit_sha, (stale, stale))
(repo / "methods" / "documents" / "extra.mthds").write_text(VALID_MTHDS.replace('"smoke"', '"extra"'), encoding="utf-8")
_git("add", "-A", cwd=repo)
_git("commit", "-m", "second version", cwd=repo)
_git("tag", "-a", "v0.2.0", "-m", "second tag", cwd=repo)
second_ref = parse_method_ref("github.com/pipelex/methods/[email protected]")
with cache.pinned_package(ref=second_ref, clone_url=clone_url) as second:
pass
assert not (tmp_path / "cache" / first.commit_sha).exists(), "an entry unused past the age bound is evicted"
assert (tmp_path / "cache" / second.commit_sha).is_dir()
def test_a_clone_being_read_survives_an_eviction(self, origin: tuple[str, Path], tmp_path: Path, mocker: MockerFixture):
"""A concurrent request's miss evicts the oldest clone, yet never the one another request is still reading."""
clone_url, repo = origin
mocker.patch("pipelex_api.method_cache.MAX_METHOD_CACHE_CLONES", 1)
cache = MethodCloneCache(root_dir=tmp_path / "cache")
(repo / "methods" / "documents" / "extra.mthds").write_text(VALID_MTHDS.replace('"smoke"', '"extra"'), encoding="utf-8")
_git("add", "-A", cwd=repo)
_git("commit", "-m", "second version", cwd=repo)
_git("tag", "-a", "v0.2.0", "-m", "second tag", cwd=repo)
second_ref = parse_method_ref("github.com/pipelex/methods/[email protected]")
with cache.pinned_package(ref=_REF, clone_url=clone_url) as first:
old = time.time() - 120
os.utime(first.clone_dir, (old, old))
with cache.pinned_package(ref=second_ref, clone_url=clone_url) as second:
pass
assert first.clone_dir.is_dir(), "a pinned clone is never evicted"
assert (first.package_dir / "documents.mthds").read_text(encoding="utf-8") == VALID_MTHDS
(repo / "methods" / "documents" / "third.mthds").write_text(VALID_MTHDS.replace('"smoke"', '"third"'), encoding="utf-8")
_git("add", "-A", cwd=repo)
_git("commit", "-m", "third version", cwd=repo)
_git("tag", "-a", "v0.3.0", "-m", "third tag", cwd=repo)
with cache.pinned_package(ref=parse_method_ref("github.com/pipelex/methods/[email protected]"), clone_url=clone_url) as third:
pass
assert not first.clone_dir.exists(), "once nothing reads a clone, the bounds evict it again"
assert not second.clone_dir.exists()
assert third.clone_dir.is_dir()
def test_nonexistent_repository_is_a_fetch_error(self, tmp_path: Path):
with pytest.raises(MethodFetchError, match="could not reach the repository") as exc_info:
resolve_remote_commit_sha(ref=_BARE_REF, clone_url=f"file://{tmp_path}/no-such-repo")
# One exit status of `git ls-remote` covers a missing repository and an unreachable host, so the
# code is the transient one until the fetch tells them apart.
assert exc_info.value.resolve_error_code() == "method.fetch_failed"
problem = exc_info.value.to_problem(view=ProblemView.CALLER)
assert problem.to_wire()["params"] == {"method_ref": _BARE_REF.ref_str}
assert _BARE_REF.ref_str in problem.detail