gitgrip 1.5.0__py3-none-any.whl

gr2/overlay/objects.py

@@ -0,0 +1,412 @@
+"""Overlay object encoding: capture source files into git objects, apply them back."""
+
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+
+from gr2.overlay.types import OverlayMeta, OverlayRef, OverlayTier
+
+TIER_A_EXTENSIONS = frozenset({".toml", ".yml", ".json"})
+TIER_A_FILENAMES = frozenset({"COMPOSE.md"})
+
+
+def capture_overlay_object(
+    overlay_store: Path,
+    source_root: Path,
+    metadata: OverlayMeta,
+) -> None:
+    if metadata.tier == OverlayTier.B:
+        _capture_tier_b(overlay_store, source_root, metadata)
+    else:
+        _capture_tier_a(overlay_store, source_root, metadata)
+
+
+def _capture_tier_a(
+    overlay_store: Path,
+    source_root: Path,
+    metadata: OverlayMeta,
+) -> None:
+    tier_a_files = _collect_tier_a_files(source_root)
+
+    blobs: dict[str, str] = {}
+    for rel_path, abs_path in tier_a_files:
+        blobs[rel_path] = _hash_blob_from_file(overlay_store, abs_path)
+
+    working_tree_oid = _build_nested_tree(overlay_store, blobs)
+    empty_tree_oid = _build_nested_tree(overlay_store, {})
+    meta_blob_oid = _hash_blob_from_bytes(overlay_store, _serialize_metadata(metadata))
+
+    _finalize_overlay_tag(
+        overlay_store, metadata, meta_blob_oid, working_tree_oid, working_tree_oid, empty_tree_oid
+    )
+
+
+def _capture_tier_b(
+    overlay_store: Path,
+    source_root: Path,
+    metadata: OverlayMeta,
+) -> None:
+    dirty_files = _get_dirty_tracked_files(source_root)
+
+    staged_blobs: dict[str, str] = {}
+    working_blobs: dict[str, str] = {}
+    deleted_paths: list[str] = []
+
+    for rel_path in dirty_files:
+        index_oid = _get_index_blob_oid(source_root, rel_path)
+        abs_path = source_root / rel_path
+
+        if index_oid is None and not abs_path.exists():
+            deleted_paths.append(rel_path)
+            continue
+
+        if index_oid is not None:
+            index_content = _read_blob_from_repo(source_root, index_oid)
+            staged_blobs[rel_path] = _hash_blob_from_bytes(overlay_store, index_content)
+
+        if abs_path.exists():
+            working_blobs[rel_path] = _hash_blob_from_file(overlay_store, abs_path)
+
+    staged_tree_oid = _build_nested_tree(overlay_store, staged_blobs)
+    working_tree_oid = _build_nested_tree(overlay_store, working_blobs)
+    empty_tree_oid = _build_nested_tree(overlay_store, {})
+
+    repo_state = _get_repo_state(source_root)
+    meta_blob_oid = _hash_blob_from_bytes(
+        overlay_store,
+        _serialize_metadata(metadata, repo_state=repo_state, deleted_paths=deleted_paths),
+    )
+
+    _finalize_overlay_tag(
+        overlay_store, metadata, meta_blob_oid, staged_tree_oid, working_tree_oid, empty_tree_oid
+    )
+
+
+def apply_overlay_object(
+    overlay_store: Path,
+    overlay_ref: OverlayRef,
+    checkout_root: Path,
+) -> None:
+    tag_oid = _git_output(overlay_store, "rev-parse", overlay_ref.ref_path)
+    structured_tree_oid = _git_output(overlay_store, "rev-parse", f"{tag_oid}^{{tree}}")
+
+    meta_blob = _read_metadata_blob(overlay_store, structured_tree_oid)
+    is_tier_b = 'tier = "source"' in meta_blob
+
+    _write_tree_to_disk(overlay_store, structured_tree_oid, "working_tree_tree", checkout_root)
+
+    if is_tier_b:
+        _apply_staged_index(overlay_store, structured_tree_oid, checkout_root)
+        _apply_deletions(meta_blob, checkout_root)
+
+
+def _finalize_overlay_tag(
+    overlay_store: Path,
+    metadata: OverlayMeta,
+    meta_blob_oid: str,
+    staged_tree_oid: str,
+    working_tree_oid: str,
+    untracked_tree_oid: str,
+) -> None:
+    structured_input = "\n".join(
+        [
+            f"100644 blob {meta_blob_oid}\tmetadata_blob",
+            f"040000 tree {staged_tree_oid}\tstaged_index_tree",
+            f"040000 tree {untracked_tree_oid}\tuntracked_blobs",
+            f"040000 tree {working_tree_oid}\tworking_tree_tree",
+        ]
+    )
+    structured_tree_oid = _git_input(overlay_store, structured_input, "mktree")
+
+    tag_content = (
+        f"object {structured_tree_oid}\n"
+        f"type tree\n"
+        f"tag {metadata.ref.name}\n"
+        f"tagger overlay-system <overlay@gr2> 0 +0000\n"
+        f"\n"
+        f"overlay: {metadata.ref.ref_path}\n"
+    )
+    tag_oid = _git_input(overlay_store, tag_content, "mktag")
+    _git_run(overlay_store, "update-ref", metadata.ref.ref_path, tag_oid)
+
+
+def _get_dirty_tracked_files(source_root: Path) -> list[str]:
+    staged = _git_lines_in_repo(source_root, "diff-index", "--cached", "--name-only", "HEAD")
+    unstaged = _git_lines_in_repo(source_root, "diff-files", "--name-only")
+    return sorted(set(staged) | set(unstaged))
+
+
+def _get_index_blob_oid(source_root: Path, rel_path: str) -> str | None:
+    output = _git_output_in_repo(source_root, "ls-files", "-s", rel_path)
+    if not output:
+        return None
+    return output.split()[1]
+
+
+def _read_blob_from_repo(repo_root: Path, blob_oid: str) -> bytes:
+    result = subprocess.run(
+        ["git", "cat-file", "blob", blob_oid],
+        cwd=repo_root,
+        check=True,
+        capture_output=True,
+    )
+    return result.stdout
+
+
+def _get_repo_state(source_root: Path) -> dict[str, object]:
+    head_commit = _git_output_in_repo(source_root, "rev-parse", "HEAD")
+    try:
+        head_ref = _git_output_in_repo(source_root, "symbolic-ref", "HEAD")
+        head_branch = head_ref.removeprefix("refs/heads/")
+        head_detached = False
+    except subprocess.CalledProcessError:
+        head_ref = ""
+        head_branch = ""
+        head_detached = True
+    return {
+        "repo": ".",
+        "head_branch": head_branch,
+        "head_ref": head_ref,
+        "head_detached": head_detached,
+        "head_commit": head_commit,
+    }
+
+
+def _read_metadata_blob(overlay_store: Path, structured_tree_oid: str) -> str:
+    return _git_output(overlay_store, "show", f"{structured_tree_oid}:metadata_blob")
+
+
+def _apply_deletions(meta_blob: str, checkout_root: Path) -> None:
+    deleted_paths = _parse_deleted_paths(meta_blob)
+    for rel_path in deleted_paths:
+        target = checkout_root / rel_path
+        if target.exists():
+            target.unlink()
+            parent = target.parent
+            if parent != checkout_root and not any(parent.iterdir()):
+                parent.rmdir()
+        subprocess.run(
+            ["git", "update-index", "--force-remove", rel_path],
+            cwd=checkout_root,
+            check=True,
+            capture_output=True,
+            text=True,
+        )
+
+
+def _parse_deleted_paths(meta_blob: str) -> list[str]:
+    import tomllib
+
+    try:
+        data = tomllib.loads(meta_blob)
+    except tomllib.TOMLDecodeError:
+        return []
+    return data.get("deleted_paths", [])
+
+
+def _write_tree_to_disk(
+    overlay_store: Path,
+    structured_tree_oid: str,
+    tree_name: str,
+    target_root: Path,
+) -> None:
+    tree_line = _git_output(overlay_store, "ls-tree", structured_tree_oid, tree_name)
+    tree_oid = tree_line.split()[2]
+
+    ls_output = _git_output(overlay_store, "ls-tree", "-r", tree_oid)
+    if not ls_output:
+        return
+
+    for line in ls_output.splitlines():
+        meta_part, file_path = line.split("\t", 1)
+        blob_oid = meta_part.split()[2]
+
+        content = subprocess.run(
+            ["git", f"--git-dir={overlay_store}", "cat-file", "blob", blob_oid],
+            check=True,
+            capture_output=True,
+        ).stdout
+
+        target = target_root / file_path
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_bytes(content)
+
+
+def _apply_staged_index(
+    overlay_store: Path,
+    structured_tree_oid: str,
+    checkout_root: Path,
+) -> None:
+    staged_line = _git_output(overlay_store, "ls-tree", structured_tree_oid, "staged_index_tree")
+    staged_tree_oid = staged_line.split()[2]
+
+    ls_output = _git_output(overlay_store, "ls-tree", "-r", staged_tree_oid)
+    if not ls_output:
+        return
+
+    for line in ls_output.splitlines():
+        meta_part, file_path = line.split("\t", 1)
+        blob_oid = meta_part.split()[2]
+
+        content = subprocess.run(
+            ["git", f"--git-dir={overlay_store}", "cat-file", "blob", blob_oid],
+            check=True,
+            capture_output=True,
+        ).stdout
+
+        result = subprocess.run(
+            ["git", "hash-object", "-w", "--stdin"],
+            cwd=checkout_root,
+            input=content,
+            check=True,
+            capture_output=True,
+        )
+        local_oid = result.stdout.strip().decode()
+
+        subprocess.run(
+            ["git", "update-index", "--add", "--cacheinfo", f"100644,{local_oid},{file_path}"],
+            cwd=checkout_root,
+            check=True,
+            capture_output=True,
+            text=True,
+        )
+
+
+def _git_output_in_repo(repo_root: Path, *args: str) -> str:
+    result = subprocess.run(
+        ["git", *args],
+        cwd=repo_root,
+        check=True,
+        capture_output=True,
+        text=True,
+    )
+    return result.stdout.strip()
+
+
+def _git_lines_in_repo(repo_root: Path, *args: str) -> list[str]:
+    result = subprocess.run(
+        ["git", *args],
+        cwd=repo_root,
+        check=True,
+        capture_output=True,
+        text=True,
+    )
+    return [line for line in result.stdout.splitlines() if line]
+
+
+def _collect_tier_a_files(source_root: Path) -> list[tuple[str, Path]]:
+    result = []
+    for path in sorted(source_root.rglob("*")):
+        if not path.is_file():
+            continue
+        if path.suffix in TIER_A_EXTENSIONS or path.name in TIER_A_FILENAMES:
+            rel = str(path.relative_to(source_root)).replace("\\", "/")
+            result.append((rel, path))
+    return result
+
+
+def _build_nested_tree(overlay_store: Path, blobs: dict[str, str]) -> str:
+    direct: list[tuple[str, str, str, str]] = []
+    subdirs: dict[str, dict[str, str]] = {}
+
+    for path, blob_oid in blobs.items():
+        parts = path.split("/", 1)
+        if len(parts) == 1:
+            direct.append((parts[0], "100644", "blob", blob_oid))
+        else:
+            subdirs.setdefault(parts[0], {})[parts[1]] = blob_oid
+
+    for dirname, sub_blobs in sorted(subdirs.items()):
+        sub_oid = _build_nested_tree(overlay_store, sub_blobs)
+        direct.append((dirname, "040000", "tree", sub_oid))
+
+    direct.sort(key=lambda e: e[0])
+    tree_input = "\n".join(f"{mode} {kind} {oid}\t{name}" for name, mode, kind, oid in direct)
+    return _git_input(overlay_store, tree_input, "mktree")
+
+
+def _hash_blob_from_file(overlay_store: Path, file_path: Path) -> str:
+    return _git_output(overlay_store, "hash-object", "-w", str(file_path))
+
+
+def _hash_blob_from_bytes(overlay_store: Path, data: bytes) -> str:
+    result = subprocess.run(
+        ["git", f"--git-dir={overlay_store}", "hash-object", "-w", "--stdin"],
+        input=data,
+        check=True,
+        capture_output=True,
+    )
+    return result.stdout.strip().decode()
+
+
+def _serialize_metadata(
+    meta: OverlayMeta,
+    *,
+    repo_state: dict[str, object] | None = None,
+    deleted_paths: list[str] | None = None,
+) -> bytes:
+    lines = [
+        f'author = "{meta.author}"',
+        f'signature = "{meta.signature}"',
+        f'tier = "{meta.tier}"',
+        f'timestamp = "{meta.timestamp}"',
+        f'trust = "{meta.trust}"',
+    ]
+    if deleted_paths:
+        items = ", ".join(f'"{p}"' for p in deleted_paths)
+        lines.append(f"deleted_paths = [{items}]")
+    elif deleted_paths is not None:
+        lines.append("deleted_paths = []")
+    lines.append("")
+    lines.append("[ref]")
+    lines.append(f'author = "{meta.ref.author}"')
+    lines.append(f'name = "{meta.ref.name}"')
+    if meta.parent_overlay_refs:
+        lines.append("")
+        lines.append("[parents]")
+        lines.append("refs = [")
+        for ref in meta.parent_overlay_refs:
+            lines.append(f'    "{ref}",')
+        lines.append("]")
+    if repo_state:
+        lines.append("")
+        lines.append("[[repo_state]]")
+        for key in ("repo", "head_branch", "head_ref", "head_detached", "head_commit"):
+            value = repo_state.get(key)
+            if isinstance(value, bool):
+                lines.append(f"{key} = {str(value).lower()}")
+            else:
+                lines.append(f'{key} = "{value}"')
+    lines.append("")
+    return "\n".join(lines).encode()
+
+
+def _git_output(git_dir: Path, *args: str) -> str:
+    result = subprocess.run(
+        ["git", f"--git-dir={git_dir}", *args],
+        check=True,
+        capture_output=True,
+        text=True,
+    )
+    return result.stdout.strip()
+
+
+def _git_input(git_dir: Path, stdin_data: str, *args: str) -> str:
+    result = subprocess.run(
+        ["git", f"--git-dir={git_dir}", *args],
+        input=stdin_data,
+        check=True,
+        capture_output=True,
+        text=True,
+    )
+    return result.stdout.strip()
+
+
+def _git_run(git_dir: Path, *args: str) -> None:
+    subprocess.run(
+        ["git", f"--git-dir={git_dir}", *args],
+        check=True,
+        capture_output=True,
+        text=True,
+    )

gr2/overlay/perf.py

@@ -0,0 +1,251 @@
+"""Performance gates: measurement harness for overlay vs git baseline comparisons."""
+
+from __future__ import annotations
+
+import statistics
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass
+class PerfGateResult:
+    gate: str
+    baseline_seconds: float
+    candidate_seconds: float
+    ratio: float
+    threshold: float
+    passed: bool
+
+    def to_json(self) -> dict[str, Any]:
+        return {
+            "gate": self.gate,
+            "baseline_seconds": self.baseline_seconds,
+            "candidate_seconds": self.candidate_seconds,
+            "ratio": self.ratio,
+            "threshold": self.threshold,
+            "passed": self.passed,
+        }
+
+
+class PerfGateFailure(Exception):
+    def __init__(self, gate: str, ratio: float, threshold: float) -> None:
+        super().__init__(
+            f"Perf gate '{gate}' failed: ratio {ratio:.2f} exceeds threshold {threshold:.2f}"
+        )
+        self.gate = gate
+        self.ratio = ratio
+        self.threshold = threshold
+
+
+def evaluate_activate_perf_gate(
+    activate_op: Callable[[], None] | list[float],
+    git_checkout_op: Callable[[], None] | list[float],
+    samples: int,
+    max_ratio: float,
+    clock: Callable[[], float] | None = None,
+) -> PerfGateResult:
+    candidate = _collect_samples(activate_op, samples, clock)
+    baseline = _collect_samples(git_checkout_op, samples, clock)
+
+    candidate_median = statistics.median(candidate)
+    baseline_median = statistics.median(baseline)
+    ratio = candidate_median / baseline_median
+
+    return PerfGateResult(
+        gate="activate_vs_git_checkout_single_file",
+        baseline_seconds=baseline_median,
+        candidate_seconds=candidate_median,
+        ratio=ratio,
+        threshold=max_ratio,
+        passed=ratio < max_ratio,
+    )
+
+
+def evaluate_status_diff_perf_gates(
+    overlay_status_op: Callable[[], None] | list[float],
+    git_status_op: Callable[[], None] | list[float],
+    overlay_diff_op: Callable[[], None] | list[float],
+    git_diff_op: Callable[[], None] | list[float],
+    samples: int,
+    max_ratio: float,
+    clock: Callable[[], float] | None = None,
+) -> dict[str, PerfGateResult]:
+    status_candidate = _collect_samples(overlay_status_op, samples, clock)
+    status_baseline = _collect_samples(git_status_op, samples, clock)
+    status_c = statistics.median(status_candidate)
+    status_b = statistics.median(status_baseline)
+    status_ratio = status_c / status_b
+
+    diff_candidate = _collect_samples(overlay_diff_op, samples, clock)
+    diff_baseline = _collect_samples(git_diff_op, samples, clock)
+    diff_c = statistics.median(diff_candidate)
+    diff_b = statistics.median(diff_baseline)
+    diff_ratio = diff_c / diff_b
+
+    return {
+        "status_vs_git_status": PerfGateResult(
+            gate="status_vs_git_status",
+            baseline_seconds=status_b,
+            candidate_seconds=status_c,
+            ratio=status_ratio,
+            threshold=max_ratio,
+            passed=status_ratio < max_ratio,
+        ),
+        "diff_vs_git_diff": PerfGateResult(
+            gate="diff_vs_git_diff",
+            baseline_seconds=diff_b,
+            candidate_seconds=diff_c,
+            ratio=diff_ratio,
+            threshold=max_ratio,
+            passed=diff_ratio < max_ratio,
+        ),
+    }
+
+
+def assert_perf_gates(results: list[PerfGateResult]) -> None:
+    for result in results:
+        if not result.passed:
+            raise PerfGateFailure(
+                gate=result.gate,
+                ratio=result.ratio,
+                threshold=result.threshold,
+            )
+
+
+@dataclass
+class TierBPerfGateResult:
+    status: str
+    error_code: str
+    capture_ratio: float
+    apply_ratio: float
+    sample_count: int
+    capture_baseline_command: str
+    apply_baseline_command: str
+
+
+def evaluate_tier_b_perf_gate(
+    *,
+    capture_samples_ms: list[float],
+    capture_baseline_samples_ms: list[float],
+    apply_samples_ms: list[float],
+    apply_baseline_samples_ms: list[float],
+    capture_baseline_command: str,
+    apply_baseline_command: str,
+    ratio_gate: float,
+    sample_count: int,
+) -> TierBPerfGateResult:
+    all_lists = [
+        capture_samples_ms,
+        capture_baseline_samples_ms,
+        apply_samples_ms,
+        apply_baseline_samples_ms,
+    ]
+    if any(not s for s in all_lists):
+        raise ValueError(f"sample_count {sample_count}: all sample lists must be non-empty")
+    if any(len(s) != sample_count for s in all_lists):
+        raise ValueError(
+            f"sample_count {sample_count}: all sample lists must match, "
+            f"got lengths {[len(s) for s in all_lists]}"
+        )
+    for samples in all_lists:
+        for v in samples:
+            if v <= 0:
+                raise ValueError(f"All durations must be positive, got {v}")
+
+    capture_ratio = statistics.median(capture_samples_ms) / statistics.median(
+        capture_baseline_samples_ms
+    )
+    apply_ratio = statistics.median(apply_samples_ms) / statistics.median(apply_baseline_samples_ms)
+
+    if capture_ratio >= ratio_gate or apply_ratio >= ratio_gate:
+        status = "degraded"
+        error_code = "tier_b_perf_gate_failed"
+    else:
+        status = "ok"
+        error_code = ""
+
+    return TierBPerfGateResult(
+        status=status,
+        error_code=error_code,
+        capture_ratio=capture_ratio,
+        apply_ratio=apply_ratio,
+        sample_count=sample_count,
+        capture_baseline_command=capture_baseline_command,
+        apply_baseline_command=apply_baseline_command,
+    )
+
+
+@dataclass
+class CrossRepoPerfGateResult:
+    status: str
+    error_code: str
+    apply_ratio: float
+    sample_count: int
+    repo_count: int
+    baseline_command: str
+
+
+def evaluate_cross_repo_perf_gate(
+    *,
+    apply_samples_ms: list[float],
+    baseline_samples_ms: list[float],
+    baseline_command: str,
+    ratio_gate: float,
+    sample_count: int,
+    repo_count: int,
+) -> CrossRepoPerfGateResult:
+    if repo_count <= 0:
+        raise ValueError(f"repo_count must be positive, got {repo_count}")
+    if not baseline_command:
+        raise ValueError("baseline_command must not be empty")
+    if sample_count < 2:
+        raise ValueError(f"sample_count must be >= 2 for statistical validity, got {sample_count}")
+
+    all_lists = [apply_samples_ms, baseline_samples_ms]
+    if any(not s for s in all_lists):
+        raise ValueError(f"sample_count {sample_count}: all sample lists must be non-empty")
+    if any(len(s) != sample_count for s in all_lists):
+        raise ValueError(
+            f"sample_count {sample_count}: all sample lists must match, "
+            f"got lengths {[len(s) for s in all_lists]}"
+        )
+    for samples in all_lists:
+        for v in samples:
+            if v <= 0:
+                raise ValueError(f"All durations must be positive, got {v}")
+
+    apply_ratio = statistics.median(apply_samples_ms) / statistics.median(baseline_samples_ms)
+
+    if apply_ratio >= ratio_gate:
+        status = "degraded"
+        error_code = "cross_repo_perf_gate_failed"
+    else:
+        status = "ok"
+        error_code = ""
+
+    return CrossRepoPerfGateResult(
+        status=status,
+        error_code=error_code,
+        apply_ratio=apply_ratio,
+        sample_count=sample_count,
+        repo_count=repo_count,
+        baseline_command=baseline_command,
+    )
+
+
+def _collect_samples(
+    op: Callable[[], None] | list[float],
+    count: int,
+    clock: Callable[[], float] | None,
+) -> list[float]:
+    if isinstance(op, list):
+        return op
+
+    samples: list[float] = []
+    for _ in range(count):
+        start = clock()
+        op()
+        end = clock()
+        samples.append(end - start)
+    return samples

gr2/overlay/refs.py

@@ -0,0 +1,36 @@
+"""Overlay ref transport: push and fetch overlay refs between bare stores."""
+
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+
+from gr2.overlay.types import OverlayRef
+
+
+def push_overlay_ref(
+    overlay_store: Path,
+    remote_store: Path,
+    overlay_ref: OverlayRef,
+) -> None:
+    refspec = f"{overlay_ref.ref_path}:{overlay_ref.ref_path}"
+    subprocess.run(
+        ["git", f"--git-dir={overlay_store}", "push", str(remote_store), refspec],
+        check=True,
+        capture_output=True,
+        text=True,
+    )
+
+
+def fetch_overlay_ref(
+    overlay_store: Path,
+    remote_store: Path,
+    overlay_ref: OverlayRef,
+) -> None:
+    refspec = f"{overlay_ref.ref_path}:{overlay_ref.ref_path}"
+    subprocess.run(
+        ["git", f"--git-dir={overlay_store}", "fetch", str(remote_store), refspec],
+        check=True,
+        capture_output=True,
+        text=True,
+    )