compforge-repokit 0.16.0__tar.gz → 0.17.0__tar.gz

{compforge_repokit-0.16.0 → compforge_repokit-0.17.0}/AGENTS.md

@@ -10,6 +10,7 @@
 ```text
 repokit/
 ├── __init__.py / model.py  # 公共 API、common 派生类型和 owner 查询
+├── validation_report.py   # Go 验证 wire report 的解码与契约校验
 ├── validation.py          # 原生 Makefile 规划、执行与整轮验证报告
 ├── dependencies.py        # 只读依赖观察与显式锁定安装；workspace 安装根与回执
 ├── _inspect.py            # 输入版本、整次调用预算与一致性观察

{compforge_repokit-0.16.0 → compforge_repokit-0.17.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: compforge-repokit
-Version: 0.16.0
+Version: 0.17.0
 Summary: Native repository inspection, content identity, Git and Forge operations
 Requires-Python: >=3.11
 Requires-Dist: harness-common<0.7,>=0.6

{compforge_repokit-0.16.0 → compforge_repokit-0.17.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "compforge-repokit"
-version = "0.16.0"
+version = "0.17.0"
 description = "Native repository inspection, content identity, Git and Forge operations"
 readme = "README.md"
 requires-python = ">=3.11"

{compforge_repokit-0.16.0 → compforge_repokit-0.17.0}/repokit/__init__.py

@@ -9,6 +9,7 @@ from ._inspect import inspect as inspect
 from .budget import operation as operation
 from .dependencies import DependencyEnvironment as DependencyEnvironment
 from .dependencies import DependencyPreparation as DependencyPreparation
+from .dependencies import dependency_witnesses as dependency_witnesses
 from .dependencies import inspect_dependencies as inspect_dependencies
 from .dependencies import prepare_dependencies as prepare_dependencies
 from .model import ComponentBinding as ComponentBinding
@@ -38,3 +39,4 @@ from .validation import lint as lint
 from .validation import plan_validation as plan_validation
 from .validation import test as test
 from .validation import validate as validate
+from .validation_report import decode_validation_report as decode_validation_report

{compforge_repokit-0.16.0 → compforge_repokit-0.17.0}/repokit/dependencies.py

@@ -376,3 +376,22 @@ def prepare_dependencies(
         )
     finally:
         lock.release()
+
+
+def dependency_witnesses(path: str | Path) -> dict[str, str] | None:
+    """Return receipt-backed input digests, or None when reuse is not justified.
+
+    @spec Receipt names and input fingerprints belong to RepoKit. No environments
+    yields an empty mapping; unreadable inputs raise rather than prove readiness.
+    @link component://docs/validation.md
+    """
+    environments = inspect_dependencies(path)
+    if any(environment.status != "ready" for environment in environments):
+        return None
+    witnesses = {}
+    for environment in environments:
+        for source in (*environment.inputs, environment.directory / _RECEIPT):
+            witnesses[str(source.resolve())] = hashlib.sha256(source.read_bytes()).hexdigest()
+    if inspect_dependencies(path) != environments:
+        return None
+    return dict(sorted(witnesses.items()))

{compforge_repokit-0.16.0 → compforge_repokit-0.17.0}/repokit/forge/__init__.py

@@ -1,5 +1,7 @@
 """Forge clients accept explicit endpoint and credentials; no application configuration."""
 
+from .connection import ForgeConnection as ForgeConnection
+from .connection import detect_provider as detect_provider
 from .creation import PullRequestCreation as PullRequestCreation
 from .creation import ensure_pull_request as ensure_pull_request
 from .github import GitHubForge as GitHubForge

compforge_repokit-0.17.0/repokit/forge/connection.py

@@ -0,0 +1,112 @@
+"""Explicit Forge access and observation assembly, without application configuration."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Literal
+
+from harness_common import Forge as ForgeIdentity
+from harness_common import Repository
+
+from .github import GitHubForge
+from .gitlab import GitLabForge
+from .model import Forge, ForgeAuthError
+from .observation import PullRequestContext, PullRequestObserver
+
+
+def detect_provider(host: str, explicit_type: str | None = None) -> Literal["github", "gitlab"]:
+    if explicit_type in ("github", "gitlab"):
+        return "github" if explicit_type == "github" else "gitlab"
+    host = host.lower()
+    return "github" if host == "github.com" or host.startswith("github.") else "gitlab"
+
+
+@dataclass(frozen=True)
+class ForgeConnection:
+    """Access configuration; never reads a caller's config or persists credentials.
+
+    @spec Provider, Forge identity, endpoint and credential changes isolate caches.
+    Query targets are explicit and never inferred from fork provenance.
+    @link component://docs/pr.md
+    """
+
+    host: str
+    token: str = field(repr=False)
+    provider: Literal["github", "gitlab"] | None = None
+    api_host: str | None = None
+    state_dir: Path = field(default_factory=lambda: Path.home() / ".repocli")
+    timeout: int = 10
+
+    def __post_init__(self) -> None:
+        if not self.host or self.timeout <= 0:
+            raise ValueError("Forge host and positive timeout are required")
+        if not self.token.strip():
+            raise ForgeAuthError(f"PR query unavailable: no credential for {self.host}")
+        object.__setattr__(self, "provider", detect_provider(self.host, self.provider))
+        object.__setattr__(self, "api_host", self.api_host or self.host)
+        object.__setattr__(self, "state_dir", Path(self.state_dir))
+
+    @property
+    def name(self) -> str:
+        return {"github.com": "github", "gitlab.com": "gitlab"}.get(self.host, self.host)
+
+    @property
+    def identity(self) -> str:
+        value = [self.provider, self.name, self.api_host, self.token]
+        return hashlib.sha256(
+            json.dumps(value, ensure_ascii=False, separators=(",", ":")).encode()
+        ).hexdigest()
+
+    def repository(self, path: str) -> Repository:
+        if not path or path.startswith("/") or path.endswith("/"):
+            raise ValueError("nonempty repository path is required")
+        return Repository(ForgeIdentity(self.name), path)
+
+    def client(self, path: str) -> Forge:
+        self.repository(path)
+        if self.provider == "github":
+            owner, separator, name = path.partition("/")
+            if not separator or not name or "/" in name:
+                raise ValueError("GitHub repository must be owner/name")
+            return GitHubForge(
+                self.api_host or self.host,
+                owner,
+                name,
+                self.token,
+                timeout=self.timeout,
+                state_dir=self.state_dir / "forge-http",
+            )
+        return GitLabForge(
+            self.api_host or self.host,
+            path,
+            self.token,
+            timeout=self.timeout,
+            state_dir=self.state_dir / "forge-http",
+        )
+
+    def pull_request_context(
+        self,
+        checkout: str | Path,
+        *,
+        source: str,
+        targets: tuple[str, ...] | None = None,
+        reader: Forge | None = None,
+    ) -> PullRequestContext:
+        observer = PullRequestObserver(
+            reader if reader is not None else self.client(source),
+            forge=self.name,
+            state_dir=self.state_dir,
+            connection=self.identity,
+            timeout=self.timeout,
+        )
+        return PullRequestContext(
+            observer,
+            checkout,
+            source=self.repository(source),
+            targets=tuple(
+                self.repository(path) for path in (targets if targets is not None else (source,))
+            ),
+        )

compforge_repokit-0.17.0/repokit/validation_report.py

@@ -0,0 +1,99 @@
+"""Decode the Go validation engine's wire report; does not execute a second engine."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Iterable
+from pathlib import Path
+from typing import Any, cast
+
+
+def decode_validation_report(
+    payload: str, *, checkout: str | Path, checks: Iterable[str] = ("lint", "test")
+) -> dict[str, Any]:
+    """Validate one report against its checkout and requested checks.
+
+    @spec Failed checks remain valid reports. Malformed or incomplete protocol
+    evidence raises ValueError; consumers decide admission and report storage.
+    @link component://docs/validation.md
+    """
+    try:
+        return _decode(payload, str(checkout), checks)
+    except (KeyError, TypeError, AttributeError) as exc:
+        raise ValueError("malformed ValidationReport structure") from exc
+
+
+def _decode(payload: str, repo: str, checks: Iterable[str]) -> dict[str, Any]:
+    data = json.loads(payload)
+    if not isinstance(data, dict) or data.get("schemaVersion") != 1:
+        raise ValueError("unsupported ValidationReport; upgrade repocli")
+    if data.get("checkout") != str(Path(repo).resolve()):
+        raise ValueError("ValidationReport checkout mismatch")
+    if any(type(data.get(key)) is not bool for key in ("inputsConsistent", "complete", "passed")):
+        raise ValueError("invalid ValidationReport outcome")
+    if not isinstance(data.get("snapshot"), str) or not data["snapshot"].startswith("sha256:"):
+        raise ValueError("ValidationReport snapshot missing")
+    if not isinstance(data.get("components"), list) or not isinstance(
+        data.get("diagnostics"), list
+    ):
+        raise ValueError("ValidationReport results missing")
+    selected = set(checks) - {"format"}
+    if not selected <= {"lint", "test"}:
+        raise ValueError("invalid requested validation checks")
+    seen: set[tuple[str, str]] = set()
+    coverage: dict[str, set[str]] = {}
+    for group in data["components"]:
+        root = group["component"]["root"]
+        if not isinstance(root, str) or not (Path(repo) / root).resolve().is_relative_to(
+            Path(repo).resolve()
+        ):
+            raise ValueError("ValidationReport Component escapes checkout")
+        for check in group["checks"]:
+            name = check["check"]
+            if name not in selected or (root, name) in seen:
+                raise ValueError("invalid or duplicate ValidationReport check")
+            seen.add((root, name))
+            sources = check.get("requestedComponents")
+            if (
+                not isinstance(sources, list)
+                or not sources
+                or any(not isinstance(source, str) for source in sources)
+                or len(set(sources)) != len(sources)
+            ):
+                raise ValueError("ValidationReport requestedComponents missing or duplicated")
+            for source in sources:
+                if not isinstance(source, str) or not (
+                    Path(repo) / source
+                ).resolve().is_relative_to(Path(repo).resolve()):
+                    raise ValueError("ValidationReport requested Component escapes checkout")
+                if name in coverage.setdefault(source, set()):
+                    raise ValueError("duplicate requested Component check")
+                coverage[source].add(name)
+            if check["scope"] not in {"full", "focused", "skipped", "unavailable"} or check[
+                "status"
+            ] not in {"passed", "failed", "skipped", "unavailable", "cancelled", "uncertain"}:
+                raise ValueError("invalid validation check status or scope")
+            if type(check["reused"]) is not bool or not isinstance(check["witnesses"], dict):
+                raise ValueError("invalid validation evidence")
+            if any(
+                not isinstance(check.get(key), str)
+                for key in (
+                    "checkedAt",
+                    "inputFingerprint",
+                    "environment",
+                    "reason",
+                    "reuseReason",
+                    "stdout",
+                    "stderr",
+                )
+            ):
+                raise ValueError("incomplete validation check result")
+            if any(
+                not isinstance(check.get(key), list)
+                or any(not isinstance(x, str) for x in check[key])
+                for key in ("command", "files")
+            ):
+                raise ValueError("invalid validation command or file list")
+    if any(checks != selected for checks in coverage.values()):
+        raise ValueError("ValidationReport omitted requested checks")
+    return cast(dict[str, Any], data)

{compforge_repokit-0.16.0 → compforge_repokit-0.17.0}/tests/test_dependencies.py

@@ -221,3 +221,26 @@ def test_declared_manager_wins_and_ambiguous_managers_are_not_guessed(repo):
     (repo / "package.json").write_text('{"name":"ambiguous"}')
     with pytest.raises(ValueError, match="Ambiguous"):
         inspect_dependencies(repo)
+
+
+def test_dependency_witnesses_follow_preparation_and_detect_stale_inputs(
+    repo, tmp_path, monkeypatch
+):
+    """@case A real preparation receipt enables reuse without caller filename knowledge."""
+    import hashlib
+
+    from repokit import dependency_witnesses
+
+    (repo / "go.mod").write_text("module example.com/fixture\n\ngo 1.23\n")
+    assert dependency_witnesses(repo) == {}
+    (repo / "go.mod").unlink()
+    node(repo)
+    assert dependency_witnesses(repo) is None
+    installer(tmp_path, monkeypatch)
+    assert prepare_dependencies(inspect_dependencies(repo)[0]).status == "ready"
+    witnesses = dependency_witnesses(repo)
+    receipt = repo / "node_modules/.repokit-dependencies.json"
+    assert witnesses[str(receipt)] == hashlib.sha256(receipt.read_bytes()).hexdigest()
+    assert set(witnesses) == {str(receipt), str(repo / "package.json"), str(repo / "bun.lock")}
+    (repo / "bun.lock").write_text("changed lock")
+    assert dependency_witnesses(repo) is None

compforge_repokit-0.17.0/tests/test_forge_connection.py

@@ -0,0 +1,44 @@
+import json
+from pathlib import Path
+
+import pytest
+
+from repokit.forge import ForgeConnection, detect_provider
+from repokit.forge.model import ForgeAuthError
+
+
+def test_connection_identity_and_context_are_shared_with_typescript(repo, tmp_path):
+    """@case Credentials, provider and endpoint isolate caches; targets stay explicit."""
+    fixture = Path(__file__).resolve().parents[3] / "conformance/forge-connection.json"
+    for row in json.loads(fixture.read_text()):
+        connection = ForgeConnection(
+            host=row["host"],
+            provider=row["provider"],
+            api_host=row["apiHost"],
+            token=row["token"],
+            state_dir=tmp_path,
+        )
+        assert connection.name == row["name"]
+        assert connection.identity == row["identity"]
+        assert row["token"] not in repr(connection)
+        context = connection.pull_request_context(repo, source="owner/repo")
+        assert context.source == connection.repository("owner/repo")
+        assert context.targets == (context.source,)
+        assert context.observer.store.root == tmp_path
+        assert context.observer.reader.state_dir == tmp_path / "forge-http"
+        explicit = connection.pull_request_context(
+            repo, source="owner/repo", targets=("upstream/repo",)
+        )
+        assert explicit.targets == (connection.repository("upstream/repo"),)
+        with pytest.raises(ValueError):
+            connection.pull_request_context(repo, source="owner/repo", targets=())
+
+
+def test_access_configuration_requires_credentials_and_valid_timeout():
+    assert detect_provider("github.example") == "github"
+    assert detect_provider("forge.example", "github") == "github"
+    assert detect_provider("forge.example") == "gitlab"
+    with pytest.raises(ForgeAuthError):
+        ForgeConnection("github.com", " ")
+    with pytest.raises(ValueError):
+        ForgeConnection("github.com", "fixture", timeout=0)

compforge_repokit-0.17.0/tests/test_validation_report.py

@@ -0,0 +1,88 @@
+import copy
+import json
+
+import pytest
+
+from repokit import decode_validation_report
+
+
+def report(checkout):
+    checks = [
+        {
+            "check": name,
+            "requestedComponents": ["."],
+            "status": "passed",
+            "scope": "full",
+            "command": ["make", name],
+            "files": [],
+            "reason": "fixture",
+            "reused": False,
+            "reuseReason": "no previous check",
+            "checkedAt": "2026-11-02T00:00:00Z",
+            "inputFingerprint": "sha256:inputs",
+            "environment": "test",
+            "witnesses": {},
+            "stdout": "",
+            "stderr": "",
+        }
+        for name in ("lint", "test")
+    ]
+    return {
+        "schemaVersion": 1,
+        "checkout": str(checkout),
+        "snapshot": "sha256:snapshot",
+        "inputsConsistent": True,
+        "complete": True,
+        "passed": True,
+        "components": [{"component": {"root": "."}, "checks": checks}],
+        "diagnostics": [],
+    }
+
+
+def test_failed_report_and_partial_fallback_groups_are_valid(tmp_path):
+    value = report(tmp_path)
+    lint, test = value["components"][0]["checks"]
+    lint["requestedComponents"] = test["requestedComponents"] = ["child"]
+    test["status"] = "failed"
+    value["passed"] = False
+    value["components"] = [
+        {"component": {"root": "."}, "checks": [lint]},
+        {"component": {"root": "child"}, "checks": [test]},
+    ]
+    assert (
+        decode_validation_report(
+            json.dumps(value), checkout=tmp_path, checks=("format", "lint", "test")
+        )
+        == value
+    )
+
+
+@pytest.mark.parametrize(
+    "mutation", ["checkout", "schema", "missing", "duplicate", "escape", "shape", "bool"]
+)
+def test_invalid_report_is_not_validation_evidence(tmp_path, mutation):
+    value = report(tmp_path)
+    if mutation == "checkout":
+        value["checkout"] = str(tmp_path / "other")
+    elif mutation == "schema":
+        value["schemaVersion"] = 2
+    elif mutation == "missing":
+        value["components"][0]["checks"].pop()
+    elif mutation == "duplicate":
+        value["components"] *= 2
+    elif mutation == "escape":
+        value["components"][0]["component"]["root"] = "../outside"
+    elif mutation == "shape":
+        value["components"] = [None]
+    else:
+        value["complete"] = 1
+    with pytest.raises(ValueError):
+        decode_validation_report(json.dumps(value), checkout=tmp_path)
+
+
+@pytest.mark.parametrize("sources", [[["child"]], [{"root": "."}], [1], [".", "."], []])
+def test_requested_component_identity_must_be_unique_strings(tmp_path, sources):
+    value = copy.deepcopy(report(tmp_path))
+    value["components"][0]["checks"][0]["requestedComponents"] = sources
+    with pytest.raises(ValueError, match="requestedComponents"):
+        decode_validation_report(json.dumps(value), checkout=tmp_path)

{compforge_repokit-0.16.0 → compforge_repokit-0.17.0}/uv.lock

@@ -17,7 +17,7 @@ wheels = [
 
 [[package]]
 name = "compforge-repokit"
-version = "0.16.0"
+version = "0.17.0"
 source = { editable = "." }
 dependencies = [
     { name = "harness-common" },