gitgrip 1.5.0__py3-none-any.whl

gr2/python_cli/target.py

@@ -0,0 +1,100 @@
+"""gr2 `target`: the stored PR target (`[settings].target` in the workspace spec).
+
+This is the WRITER for the value gr2 `prune` already reads. gr1's `gr target set`
+writes the gr1 manifest (`.gitgrip/...`), a different file; this writes
+`.grip/workspace_spec.toml`, which is what gr2 reads.
+
+The write is a faithful round-trip -- `tomllib.load` the whole spec, set (or
+remove) `settings.target`, `tomli_w.dumps` the whole thing back, atomically --
+so every other field (repos, units, workspace_name, an existing merge_method)
+survives untouched. It deliberately does NOT go through `_write_workspace_spec`,
+which regenerates the spec from repos/units alone and emits no `[settings]` table
+at all (it would silently drop merge_method). The spec is machine-written, so the
+round-trip dropping TOML comments is a non-issue -- there are none to keep.
+"""
+
+from __future__ import annotations
+
+import os
+import tempfile
+import tomllib
+from pathlib import Path
+
+import tomli_w
+
+
+class TargetError(Exception):
+    pass
+
+
+_SPEC_REL = (".grip", "workspace_spec.toml")
+
+
+def spec_path(workspace_root: Path) -> Path:
+    return workspace_root.joinpath(*_SPEC_REL)
+
+
+def _load(workspace_root: Path) -> dict:
+    path = spec_path(workspace_root)
+    if not path.is_file():
+        raise TargetError(
+            f"no workspace spec at {path}: a stored target needs a workspace "
+            f"(run inside a gripspace, or set --target on prune directly)"
+        )
+    with path.open("rb") as fh:
+        return tomllib.load(fh)
+
+
+def _settings(spec: dict) -> dict:
+    settings = spec.get("settings", {})
+    if not isinstance(settings, dict):
+        raise TargetError("workspace spec [settings] must be a table")
+    return settings
+
+
+def _atomic_write(workspace_root: Path, spec: dict) -> None:
+    path = spec_path(workspace_root)
+    data = tomli_w.dumps(spec)
+    # Atomic: write a sibling temp file then os.replace, so a crash mid-write
+    # can never leave a truncated spec.
+    fd, tmp = tempfile.mkstemp(dir=str(path.parent), prefix=".workspace_spec.", suffix=".toml")
+    try:
+        with os.fdopen(fd, "w") as fh:
+            fh.write(data)
+        os.replace(tmp, path)
+    finally:
+        if os.path.exists(tmp):
+            os.unlink(tmp)
+
+
+def show_target(workspace_root: Path) -> str | None:
+    """The stored `[settings].target`, or None if unset."""
+    value = _settings(_load(workspace_root)).get("target")
+    if value is None:
+        return None
+    if not isinstance(value, str):
+        raise TargetError("workspace setting target must be a string")
+    return value
+
+
+def set_target(workspace_root: Path, branch: str) -> None:
+    """Write `[settings].target = <branch>`, preserving every other field."""
+    if not branch:
+        raise TargetError("target branch must be a non-empty name")
+    spec = _load(workspace_root)
+    spec.setdefault("settings", {})
+    if not isinstance(spec["settings"], dict):
+        raise TargetError("workspace spec [settings] must be a table")
+    spec["settings"]["target"] = branch
+    _atomic_write(workspace_root, spec)
+
+
+def unset_target(workspace_root: Path) -> bool:
+    """Remove `[settings].target` if present. Returns True if something was removed."""
+    spec = _load(workspace_root)
+    settings = spec.get("settings")
+    if isinstance(settings, dict) and "target" in settings:
+        del settings["target"]
+        _atomic_write(workspace_root, spec)
+        return True
+    return False

gr2/python_cli/workspace_snapshot.py

@@ -0,0 +1,105 @@
+"""Capture a materialized lane's resolved repository state as one kind=workspace
+gr commit (R2 Milestone 1, the section-5 semantic tree for the workspace kind).
+
+The workspace gr commit is a reproduction coordinate: it records, per repo, the
+exact head a checkout must materialize plus the base it builds on. A repo with
+uncommitted changes is REFUSED, not recorded — snapshotting a dirty tree would
+record a coordinate that does not reproduce the author's actual state. Commit
+the lane first (``gr2 commit`` lane-aware), then snapshot.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from gr2.prototypes import lane_workspace_prototype as lane_proto
+
+from . import grip
+from .gitops import git, repo_dirty
+
+
+class WorkspaceSnapshotError(Exception):
+    pass
+
+
+def _resolve_head(repo_root: Path, key: str, fork_base_sha: str | None) -> tuple[str, str]:
+    """(commit, base) for one lane repo.
+
+    `commit` is HEAD. `base` is the RECORDED fork base, never derived
+    from HEAD^: a lane with N commits must record where its work began, and HEAD^
+    is only the (N-1)th commit. A lane with no recorded fork base reads base as
+    unknown and is REFUSED here — the reproduction path never substitutes HEAD^ or
+    a live merge-base for a coordinate it does not actually know.
+    """
+    head = git(repo_root, "rev-parse", "--verify", "HEAD")
+    if head.returncode != 0 or not head.stdout.strip():
+        raise WorkspaceSnapshotError(f"repo {key} has no HEAD to snapshot")
+    commit = head.stdout.strip()
+    if not fork_base_sha:
+        raise WorkspaceSnapshotError(
+            f"repo {key} has no recorded fork base; base is unknown. Recreate the lane "
+            "with a recorded fork base; the snapshot will not substitute HEAD^."
+        )
+    # The recorded fork base must be a real commit in this repo and an ancestor of
+    # HEAD — otherwise it is not a coordinate HEAD actually builds on.
+    if git(repo_root, "rev-parse", "--verify", "--quiet", f"{fork_base_sha}^{{commit}}").returncode != 0:
+        raise WorkspaceSnapshotError(
+            f"repo {key} recorded fork base {fork_base_sha} is not a commit in this repo"
+        )
+    if git(repo_root, "merge-base", "--is-ancestor", fork_base_sha, commit).returncode != 0:
+        raise WorkspaceSnapshotError(
+            f"repo {key} recorded fork base {fork_base_sha} is not an ancestor of HEAD {commit}"
+        )
+    return commit, fork_base_sha
+
+
+def resolve_lane_repos(workspace_root: Path, owner_unit: str, lane_name: str) -> list[dict[str, str]]:
+    """Resolve every repo of a materialized lane into the section-5 fields.
+
+    Refuses a repo with uncommitted changes (a snapshot must reproduce).
+    """
+    workspace_root = Path(workspace_root).resolve()
+    doc = lane_proto.load_lane_doc(workspace_root, owner_unit, lane_name)
+    fork_base = doc.get("fork_base", {})
+    spec = lane_proto.load_workspace_spec(workspace_root)
+    spec_by_name = {r.get("name"): r for r in spec.get("repos", [])}
+    lane_root = lane_proto.lane_dir(workspace_root, owner_unit, lane_name)
+
+    resolved: list[dict[str, str]] = []
+    for key in doc.get("repos", []):
+        repo_root = lane_root / "repos" / key
+        if not (repo_root / ".git").exists():
+            raise WorkspaceSnapshotError(f"repo {key} is not materialized at {repo_root}")
+        if repo_dirty(repo_root):
+            raise WorkspaceSnapshotError(
+                f"repo {key} has uncommitted changes; commit the lane before snapshotting"
+            )
+        repo_spec = spec_by_name.get(key)
+        if not repo_spec:
+            raise WorkspaceSnapshotError(f"repo {key} is not in the workspace spec")
+        commit, base = _resolve_head(repo_root, key, fork_base.get(key, {}).get("sha"))
+        resolved.append({
+            "key": key,
+            "remote": str(repo_spec.get("url", "")),
+            "path": str(repo_spec.get("path", "")),
+            "commit": commit,
+            "base": base,
+        })
+    return resolved
+
+
+def snapshot_lane(workspace_root: Path, owner_unit: str, lane_name: str) -> str:
+    """Resolve a materialized lane and write one kind=workspace gr commit.
+
+    Returns the gr commit id (the reproduction coordinate).
+    """
+    workspace_root = Path(workspace_root).resolve()
+    repos = resolve_lane_repos(workspace_root, owner_unit, lane_name)
+    if not repos:
+        raise WorkspaceSnapshotError(f"lane {owner_unit}/{lane_name} has no repos to snapshot")
+    return grip.create_workspace_commit(workspace_root, repos)
+
+
+def read_snapshot(workspace_root: Path, commit: str) -> list[dict[str, str]]:
+    """Decode a kind=workspace gr commit's resolved repository fields."""
+    return grip.read_workspace_commit(Path(workspace_root).resolve(), commit)

gr2/schemas/gr2-materialization-plan-v1.schema.json

@@ -0,0 +1,191 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:synapt:gr2:materialization-plan:v1",
+  "title": "gr2 MaterializationPlan v1",
+  "description": "Identity-free, one-opaque-unit materialization plan consumed by the neutral gr2 executor.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version",
+    "plan_id",
+    "unit_key",
+    "workspace_spec_sha256",
+    "operations"
+  ],
+  "properties": {
+    "schema_version": {
+      "const": 1
+    },
+    "plan_id": {
+      "$ref": "#/$defs/opaqueToken"
+    },
+    "unit_key": {
+      "$ref": "#/$defs/opaqueToken"
+    },
+    "workspace_spec_sha256": {
+      "$ref": "#/$defs/sha256"
+    },
+    "operations": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "oneOf": [
+          {
+            "$ref": "#/$defs/cloneOperation"
+          },
+          {
+            "$ref": "#/$defs/venvOperation"
+          },
+          {
+            "$ref": "#/$defs/editableInstallOperation"
+          },
+          {
+            "$ref": "#/$defs/projectFileOperation"
+          }
+        ]
+      }
+    }
+  },
+  "$defs": {
+    "opaqueToken": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 128,
+      "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$"
+    },
+    "sha256": {
+      "type": "string",
+      "pattern": "^[0-9a-f]{64}$"
+    },
+    "nonEmptyString": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 2048,
+      "pattern": "^[^\\u0000]+$"
+    },
+    "workspaceRelativePath": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 1024,
+      "pattern": "^(?![~/])(?!.*\\\\)(?!.*//)(?!.*(?:^|/)\\.{1,2}(?:/|$))[^\\u0000]+$"
+    },
+    "cacheReferencePath": {
+      "type": "string",
+      "pattern": "^\\.grip/cache/repos/[A-Za-z0-9][A-Za-z0-9._-]{0,127}\\.git$"
+    },
+    "stagedInputPath": {
+      "type": "string",
+      "pattern": "^\\.grip/staging/inputs/[A-Za-z0-9][A-Za-z0-9._-]{0,127}$"
+    },
+    "cloneOperation": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "kind",
+        "repo_url",
+        "dest_path",
+        "branch"
+      ],
+      "properties": {
+        "kind": {
+          "const": "clone"
+        },
+        "repo_url": {
+          "$ref": "#/$defs/nonEmptyString"
+        },
+        "dest_path": {
+          "$ref": "#/$defs/workspaceRelativePath"
+        },
+        "branch": {
+          "$ref": "#/$defs/nonEmptyString"
+        },
+        "reference_base": {
+          "$ref": "#/$defs/cacheReferencePath"
+        }
+      }
+    },
+    "venvOperation": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "kind",
+        "dest_path",
+        "engine",
+        "python"
+      ],
+      "properties": {
+        "kind": {
+          "const": "venv"
+        },
+        "dest_path": {
+          "$ref": "#/$defs/workspaceRelativePath"
+        },
+        "engine": {
+          "const": "uv"
+        },
+        "python": {
+          "$ref": "#/$defs/nonEmptyString"
+        }
+      }
+    },
+    "editableInstallOperation": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "kind",
+        "venv_path",
+        "source_path",
+        "extras"
+      ],
+      "properties": {
+        "kind": {
+          "const": "editable_install"
+        },
+        "venv_path": {
+          "$ref": "#/$defs/workspaceRelativePath"
+        },
+        "source_path": {
+          "$ref": "#/$defs/workspaceRelativePath"
+        },
+        "extras": {
+          "type": "array",
+          "uniqueItems": true,
+          "items": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 128,
+            "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$"
+          }
+        }
+      }
+    },
+    "projectFileOperation": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "kind",
+        "source_path",
+        "source_sha256",
+        "dest_path",
+        "mode"
+      ],
+      "properties": {
+        "kind": {
+          "const": "project_file"
+        },
+        "source_path": {
+          "$ref": "#/$defs/stagedInputPath"
+        },
+        "source_sha256": {
+          "$ref": "#/$defs/sha256"
+        },
+        "dest_path": {
+          "$ref": "#/$defs/workspaceRelativePath"
+        },
+        "mode": {
+          "const": "copy"
+        }
+      }
+    }
+  }
+}

gr2_overlay/__init__.py

@@ -0,0 +1,37 @@
+"""Deprecated compatibility shim: ``gr2_overlay`` was renamed to ``gr2.overlay``.
+
+Import ``gr2.overlay`` instead. Every submodule of the real package is aliased
+through ``sys.modules`` here, so ``gr2_overlay.units`` IS ``gr2.overlay.units``
+(the same module object, not a parallel copy) — a consumer that has not yet
+migrated keeps working with no behavioural drift. Removed in the release after
+1.5.0; downstream consumers migrate to ``gr2.overlay`` before then.
+"""
+from __future__ import annotations
+
+import importlib as _importlib
+import pkgutil as _pkgutil
+import sys as _sys
+import warnings as _warnings
+
+_warnings.warn(
+    "gr2_overlay is deprecated and will be removed in the release after 1.5.0; "
+    "import gr2.overlay instead.",
+    DeprecationWarning,
+    stacklevel=2,
+)
+
+_real = _importlib.import_module("gr2.overlay")
+
+# Alias every submodule so `import gr2_overlay.X` and `from gr2_overlay.X import Y`
+# resolve to the SAME module object as gr2.overlay.X. Discovered dynamically from
+# the real package so a new submodule is covered without editing this shim.
+for _info in _pkgutil.iter_modules(_real.__path__):
+    _mod = _importlib.import_module(f"gr2.overlay.{_info.name}")
+    _sys.modules[f"{__name__}.{_info.name}"] = _mod
+    globals()[_info.name] = _mod
+
+# Re-export the real package's declared public names (`from gr2_overlay import X`).
+for _attr in getattr(_real, "__all__", ()):
+    globals()[_attr] = getattr(_real, _attr)
+
+del _importlib, _pkgutil, _sys, _warnings, _info, _mod, _real