pl_vendor 0.1.0__tar.gz

pl_vendor-0.1.0/PKG-INFO

@@ -0,0 +1,75 @@
+Metadata-Version: 2.4
+Name: pl_vendor
+Version: 0.1.0
+Summary: Vendor Git repositories as ordinary files with a reproducible lockfile
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+
+# pl_vendor
+
+`pl_vendor` copies Git repositories into another repository as ordinary files and
+records their exact commits in a deterministic YAML lockfile. It supports optional
+downstream patches and can verify that checked-in vendor trees still match their
+locked upstream commits.
+
+## Requirements
+
+- Python 3.13 or newer
+- Git 2.30 or newer
+- uv 0.9 or newer by default
+
+The package has no Python runtime dependencies.
+
+Every command runs a preflight check before reading or changing vendored trees. Library
+callers that use another environment runner can pass an `ExecutableBackend` to
+`VendorProject.discover()`; that executable and its declared minimum version are checked
+in place of uv. Git is always checked.
+
+## Configuration
+
+Create `vendor.toml` at the root of the consuming Git repository:
+
+```toml
+schema_version = 1
+
+[dependencies.example]
+path = "vendor/example"
+url = "https://github.com/example/example.git"
+branch = "release"
+```
+
+The generated `vendor-lock.yaml` records the resolved commit:
+
+```yaml
+lockfileVersion: 1
+
+dependencies:
+  example: '0123456789abcdef0123456789abcdef01234567'
+```
+
+Optional patches live at `.vendor-patches/<dependency-name>.patch` and are applied
+after copying the upstream tree.
+
+## Commands
+
+```sh
+pl-vendor update
+pl-vendor update example
+pl-vendor check
+pl-vendor verify
+```
+
+Each command discovers the consuming repository from the current directory. Pass
+`--root PATH` after the command to operate on a different repository.
+
+## Development
+
+```sh
+uv sync --dev
+uv run pytest
+uv run pyright
+uv run ruff format --check .
+```
+
+The internal test suite is kept in `src/pl_vendor/tests` so the package remains
+self-contained while it is developed or embedded elsewhere.

pl_vendor-0.1.0/README.md

@@ -0,0 +1,68 @@
+# pl_vendor
+
+`pl_vendor` copies Git repositories into another repository as ordinary files and
+records their exact commits in a deterministic YAML lockfile. It supports optional
+downstream patches and can verify that checked-in vendor trees still match their
+locked upstream commits.
+
+## Requirements
+
+- Python 3.13 or newer
+- Git 2.30 or newer
+- uv 0.9 or newer by default
+
+The package has no Python runtime dependencies.
+
+Every command runs a preflight check before reading or changing vendored trees. Library
+callers that use another environment runner can pass an `ExecutableBackend` to
+`VendorProject.discover()`; that executable and its declared minimum version are checked
+in place of uv. Git is always checked.
+
+## Configuration
+
+Create `vendor.toml` at the root of the consuming Git repository:
+
+```toml
+schema_version = 1
+
+[dependencies.example]
+path = "vendor/example"
+url = "https://github.com/example/example.git"
+branch = "release"
+```
+
+The generated `vendor-lock.yaml` records the resolved commit:
+
+```yaml
+lockfileVersion: 1
+
+dependencies:
+  example: '0123456789abcdef0123456789abcdef01234567'
+```
+
+Optional patches live at `.vendor-patches/<dependency-name>.patch` and are applied
+after copying the upstream tree.
+
+## Commands
+
+```sh
+pl-vendor update
+pl-vendor update example
+pl-vendor check
+pl-vendor verify
+```
+
+Each command discovers the consuming repository from the current directory. Pass
+`--root PATH` after the command to operate on a different repository.
+
+## Development
+
+```sh
+uv sync --dev
+uv run pytest
+uv run pyright
+uv run ruff format --check .
+```
+
+The internal test suite is kept in `src/pl_vendor/tests` so the package remains
+self-contained while it is developed or embedded elsewhere.

pl_vendor-0.1.0/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["setuptools>=69"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pl_vendor"
+version = "0.1.0"
+description = "Vendor Git repositories as ordinary files with a reproducible lockfile"
+readme = "README.md"
+requires-python = ">=3.13"
+dependencies = []
+
+[project.scripts]
+pl-vendor = "pl_vendor.cli:main"
+
+[dependency-groups]
+dev = [
+  "pyright",
+  "pytest",
+  "ruff",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["src/pl_vendor/tests"]
+
+[tool.pyright]
+include = ["src/pl_vendor"]
+
+[tool.uv]
+required-version = ">=0.9.0"
+
+[tool.ruff]
+target-version = "py313"

pl_vendor-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

pl_vendor-0.1.0/src/pl_vendor/__init__.py

@@ -0,0 +1,32 @@
+"""Vendor Git repositories as ordinary files with a reproducible lockfile."""
+
+from .config import (
+    VendorConfigError,
+    VendorDependency,
+    load_vendor_config,
+    load_vendor_lock,
+    validate_vendor_lock,
+    write_vendor_lock,
+)
+from .preflight import (
+    MINIMUM_GIT_VERSION,
+    MINIMUM_UV_VERSION,
+    ExecutableBackend,
+    PreflightError,
+)
+from .project import VendorError, VendorProject
+
+__all__ = [
+    "MINIMUM_GIT_VERSION",
+    "MINIMUM_UV_VERSION",
+    "ExecutableBackend",
+    "PreflightError",
+    "VendorConfigError",
+    "VendorDependency",
+    "VendorError",
+    "VendorProject",
+    "load_vendor_config",
+    "load_vendor_lock",
+    "validate_vendor_lock",
+    "write_vendor_lock",
+]

pl_vendor-0.1.0/src/pl_vendor/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

pl_vendor-0.1.0/src/pl_vendor/cli.py

@@ -0,0 +1,59 @@
+"""Command-line interface for pl-vendor."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from .project import VendorError, VendorProject
+
+
+def _add_root_argument(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument(
+        "--root",
+        type=Path,
+        default=None,
+        help="Repository to operate on (defaults to the current Git repository).",
+    )
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="pl-vendor",
+        description="Vendor Git repositories as ordinary, reproducible files.",
+    )
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    update_parser = subparsers.add_parser(
+        "update", help="Update one or all vendored dependencies."
+    )
+    update_parser.add_argument("dependency", nargs="?", default="all")
+    _add_root_argument(update_parser)
+
+    check_parser = subparsers.add_parser(
+        "check", help="Check whether newer upstream revisions exist."
+    )
+    _add_root_argument(check_parser)
+
+    verify_parser = subparsers.add_parser(
+        "verify", help="Verify vendored files against their locked revisions."
+    )
+    _add_root_argument(verify_parser)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    try:
+        project = VendorProject.discover(args.root)
+        if args.command == "update":
+            project.update(args.dependency)
+            return 0
+        if args.command == "check":
+            return 0 if project.check() else 1
+        return 0 if project.verify() else 1
+    except VendorError as exc:
+        print(f"pl-vendor: error: {exc}", file=sys.stderr)
+        return 2

pl_vendor-0.1.0/src/pl_vendor/config.py

@@ -0,0 +1,162 @@
+"""Read and write pl-vendor manifests and lockfiles."""
+
+from __future__ import annotations
+
+import re
+import tomllib
+from dataclasses import dataclass
+from pathlib import Path, PurePosixPath
+
+SCHEMA_VERSION = 1
+LOCKFILE_VERSION = 1
+NAME_EXPRESSION = r"[A-Za-z0-9][A-Za-z0-9._-]*"
+REVISION_EXPRESSION = r"[0-9a-f]{40}"
+NAME_PATTERN = re.compile(rf"{NAME_EXPRESSION}\Z")
+REVISION_PATTERN = re.compile(rf"{REVISION_EXPRESSION}\Z")
+LOCK_ENTRY_PATTERN = re.compile(
+    rf"  (?P<name>{NAME_EXPRESSION}): '(?P<revision>{REVISION_EXPRESSION})'\Z"
+)
+
+
+class VendorConfigError(ValueError):
+    """Raised when vendoring configuration does not satisfy its schema."""
+
+
+@dataclass(frozen=True, slots=True)
+class VendorDependency:
+    name: str
+    path: str
+    url: str
+    branch: str
+
+
+def load_vendor_config(path: Path) -> dict[str, VendorDependency]:
+    try:
+        with path.open("rb") as config_file:
+            config = tomllib.load(config_file)
+    except (OSError, tomllib.TOMLDecodeError) as exc:
+        raise VendorConfigError(f"Could not read {path}: {exc}") from exc
+
+    if config.get("schema_version") != SCHEMA_VERSION:
+        raise VendorConfigError(f"{path} must set schema_version = {SCHEMA_VERSION}.")
+
+    raw_dependencies = config.get("dependencies")
+    if not isinstance(raw_dependencies, dict) or not raw_dependencies:
+        raise VendorConfigError(f"{path} must declare at least one dependency.")
+
+    dependencies: dict[str, VendorDependency] = {}
+    claimed_paths: set[str] = set()
+    expected_fields = {"path", "url", "branch"}
+    for name, raw_dependency in raw_dependencies.items():
+        if not isinstance(name, str) or NAME_PATTERN.fullmatch(name) is None:
+            raise VendorConfigError(f"Invalid dependency name: {name!r}.")
+        if not isinstance(raw_dependency, dict):
+            raise VendorConfigError(f"Dependency {name!r} must be a TOML table.")
+
+        missing = expected_fields - raw_dependency.keys()
+        unexpected = raw_dependency.keys() - expected_fields
+        if missing:
+            raise VendorConfigError(
+                f"Dependency {name!r} is missing: {', '.join(sorted(missing))}."
+            )
+        if unexpected:
+            raise VendorConfigError(
+                f"Dependency {name!r} has unknown fields: "
+                f"{', '.join(sorted(unexpected))}."
+            )
+
+        values: dict[str, str] = {}
+        for field in ("path", "url", "branch"):
+            value = raw_dependency[field]
+            if not isinstance(value, str) or not value.strip():
+                raise VendorConfigError(
+                    f"Dependency {name!r} field {field!r} must be a nonempty string."
+                )
+            values[field] = value
+
+        dependency_path = PurePosixPath(values["path"])
+        if (
+            dependency_path.is_absolute()
+            or dependency_path == PurePosixPath(".")
+            or ".." in dependency_path.parts
+        ):
+            raise VendorConfigError(
+                f"Dependency {name!r} path must stay within the repository."
+            )
+        if values["path"] in claimed_paths:
+            raise VendorConfigError(
+                f"More than one dependency uses path {values['path']!r}."
+            )
+        claimed_paths.add(values["path"])
+
+        dependencies[name] = VendorDependency(name=name, **values)
+
+    return dependencies
+
+
+def load_vendor_lock(path: Path) -> dict[str, str]:
+    """Load the deliberately small, generated YAML lockfile format."""
+    try:
+        lines = path.read_text(encoding="utf-8").splitlines()
+    except OSError as exc:
+        raise VendorConfigError(f"Could not read {path}: {exc}") from exc
+
+    header = [f"lockfileVersion: {LOCKFILE_VERSION}", "", "dependencies:"]
+    if lines[:3] != header:
+        raise VendorConfigError(
+            f"{path} must start with lockfileVersion: {LOCKFILE_VERSION} "
+            "followed by a dependencies mapping."
+        )
+
+    revisions: dict[str, str] = {}
+    for line in lines[3:]:
+        match = LOCK_ENTRY_PATTERN.fullmatch(line)
+        if match is None:
+            raise VendorConfigError(f"Invalid dependency entry in {path}: {line!r}.")
+        name = match.group("name")
+        if name in revisions:
+            raise VendorConfigError(f"Duplicate dependency {name!r} in {path}.")
+        revisions[name] = match.group("revision")
+
+    if not revisions:
+        raise VendorConfigError(f"{path} must lock at least one dependency.")
+    return revisions
+
+
+def validate_vendor_lock(
+    path: Path, dependencies: dict[str, VendorDependency]
+) -> dict[str, str]:
+    revisions = load_vendor_lock(path)
+    expected_names = set(dependencies)
+    locked_names = set(revisions)
+    missing = expected_names - locked_names
+    unexpected = locked_names - expected_names
+    if missing:
+        raise VendorConfigError(
+            f"{path} is missing dependencies: {', '.join(sorted(missing))}."
+        )
+    if unexpected:
+        raise VendorConfigError(
+            f"{path} has unknown dependencies: {', '.join(sorted(unexpected))}."
+        )
+    return revisions
+
+
+def write_vendor_lock(
+    path: Path,
+    dependencies: dict[str, VendorDependency],
+    revisions: dict[str, str],
+) -> None:
+    lines = [f"lockfileVersion: {LOCKFILE_VERSION}", "", "dependencies:"]
+    for name in dependencies:
+        revision = revisions.get(name)
+        if revision is not None:
+            if REVISION_PATTERN.fullmatch(revision) is None:
+                raise VendorConfigError(
+                    f"Invalid revision for dependency {name!r}: {revision!r}."
+                )
+            lines.append(f"  {name}: '{revision}'")
+    try:
+        path.write_text("\n".join(lines) + "\n", encoding="utf-8")
+    except OSError as exc:
+        raise VendorConfigError(f"Could not write {path}: {exc}") from exc

pl_vendor-0.1.0/src/pl_vendor/preflight.py

@@ -0,0 +1,75 @@
+"""Executable and version checks required by pl-vendor."""
+
+from __future__ import annotations
+
+import re
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+
+MINIMUM_GIT_VERSION = (2, 30, 0)
+MINIMUM_UV_VERSION = (0, 9, 0)
+VERSION_PATTERN = re.compile(r"(?<!\d)(\d+(?:\.\d+)+)")
+
+
+class PreflightError(RuntimeError):
+    """Raised when a required executable is unavailable or too old."""
+
+
+@dataclass(frozen=True, slots=True)
+class ExecutableBackend:
+    """An executable that prepares or runs the pl-vendor environment."""
+
+    executable: str
+    minimum_version: tuple[int, ...]
+    version_arguments: tuple[str, ...] = ("--version",)
+
+    @property
+    def minimum_version_text(self) -> str:
+        return ".".join(str(part) for part in self.minimum_version)
+
+
+UV_BACKEND = ExecutableBackend("uv", MINIMUM_UV_VERSION)
+GIT_BACKEND = ExecutableBackend("git", MINIMUM_GIT_VERSION)
+
+
+def _version_is_sufficient(
+    installed: tuple[int, ...], minimum: tuple[int, ...]
+) -> bool:
+    width = max(len(installed), len(minimum))
+    return installed + (0,) * (width - len(installed)) >= minimum + (0,) * (
+        width - len(minimum)
+    )
+
+
+def check_executable(backend: ExecutableBackend, *, cwd: Path) -> tuple[int, ...]:
+    """Return an executable's parsed version after enforcing its minimum."""
+    try:
+        result = subprocess.run(
+            [backend.executable, *backend.version_arguments],
+            cwd=cwd,
+            check=False,
+            text=True,
+            capture_output=True,
+        )
+    except FileNotFoundError as exc:
+        raise PreflightError(
+            f"Required executable {backend.executable!r} was not found; "
+            f"install version {backend.minimum_version_text} or newer."
+        ) from exc
+
+    version_output = f"{result.stdout}\n{result.stderr}"
+    match = VERSION_PATTERN.search(version_output)
+    if result.returncode != 0 or match is None:
+        raise PreflightError(
+            f"Could not determine the installed {backend.executable!r} version."
+        )
+
+    installed = tuple(int(part) for part in match.group(1).split("."))
+    if not _version_is_sufficient(installed, backend.minimum_version):
+        installed_text = ".".join(str(part) for part in installed)
+        raise PreflightError(
+            f"{backend.executable!r} {installed_text} is too old; "
+            f"version {backend.minimum_version_text} or newer is required."
+        )
+    return installed