h2h-dev-tools 0.2.1__py3-none-any.whl

h2h_dev_tools/__init__.py

@@ -0,0 +1 @@
+"""Shared, repository-independent development mechanisms."""

h2h_dev_tools/__main__.py

@@ -0,0 +1,43 @@
+"""Explicit source synchronization and offline verification commands."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from .bundle import sync_bundle
+from .bundle_verify import BundleError, verify_bundle
+from .migrate_v1 import migrate_v1
+
+
+def main(arguments: list[str] | None = None) -> int:
+    """Execute one toolkit operation against an explicitly selected repository."""
+    parser = argparse.ArgumentParser(description=__doc__)
+    commands = parser.add_subparsers(dest="command", required=True)
+    for name in ("sync", "verify", "migrate-v1"):
+        command = commands.add_parser(name)
+        command.add_argument("--repository", required=True, type=Path)
+    options = parser.parse_args(arguments)
+    try:
+        if options.command in {"sync", "migrate-v1"}:
+            operation = sync_bundle if options.command == "sync" else migrate_v1
+            changed = operation(options.repository)
+            print(
+                "Source bundle synchronized."
+                if changed
+                else "Source bundle is unchanged."
+            )
+        else:
+            manifest = verify_bundle(options.repository)
+            print(
+                f"Verified h2h-dev-tools {manifest['toolkit_version']} source bundle."
+            )
+    except BundleError as error:
+        print(f"h2h-dev-tools: {error}", file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

h2h_dev_tools/atomic_files.py

@@ -0,0 +1,32 @@
+"""Publish complete byte payloads through an atomic filesystem name operation."""
+
+from __future__ import annotations
+
+import os
+import tempfile
+from pathlib import Path
+
+
+def publish_bytes(path: Path, content: bytes, *, overwrite: bool = False) -> None:
+    """Publish in an existing parent, preserving other writers unless requested.
+
+    The temporary file is flushed and fsynced before publication. This provides
+    atomic visibility, not a directory-fsync or power-loss durability contract.
+    Callers own parent creation, serialization, target policy and permissions.
+    """
+    temporary: Path | None = None
+    try:
+        with tempfile.NamedTemporaryFile(
+            mode="wb", dir=path.parent, prefix=f".{path.name}.", delete=False
+        ) as stream:
+            temporary = Path(stream.name)
+            stream.write(content)
+            stream.flush()
+            os.fsync(stream.fileno())
+        if overwrite:
+            os.replace(temporary, path)
+        else:
+            os.link(temporary, path)
+    finally:
+        if temporary is not None:
+            temporary.unlink(missing_ok=True)

h2h_dev_tools/bundle.py

@@ -0,0 +1,107 @@
+"""Export reviewed toolkit source into a consumer's committed Git tree."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import tempfile
+from collections.abc import Callable
+from importlib import metadata
+from pathlib import Path
+
+from .bundle_verify import (
+    MANIFEST_NAME,
+    BundleError,
+    BundleManifest,
+    bundle_directory,
+    cache_files,
+    component_files,
+    payload_digest,
+    regular_bytes,
+    repository_components,
+    validate_manifest,
+    verify_bundle,
+)
+
+
+def _source_payload(components: list[str]) -> tuple[dict[str, bytes], BundleManifest]:
+    try:
+        version = metadata.version("h2h-dev-tools")
+    except metadata.PackageNotFoundError as error:
+        raise BundleError(
+            "Install h2h-dev-tools before exporting its source bundle"
+        ) from error
+    source = Path(__file__).parent
+    payload = {
+        name: regular_bytes(source / name)
+        for name in sorted(component_files(components))
+    }
+    hashes = {
+        name: hashlib.sha256(content).hexdigest() for name, content in payload.items()
+    }
+    manifest: BundleManifest = {
+        "schema_version": 2,
+        "components": components,
+        "toolkit_name": "h2h-dev-tools",
+        "toolkit_version": version,
+        "payload_sha256": payload_digest(hashes),
+        "files": hashes,
+    }
+    return payload, validate_manifest(manifest)
+
+
+def sync_bundle(repository: Path) -> bool:
+    """Replace only a verified generated file set; return whether bytes changed."""
+    return replace_bundle(
+        repository, lambda: verify_bundle(repository, check_selection=False)
+    )
+
+
+def replace_bundle(
+    repository: Path, verify_existing: Callable[[], BundleManifest]
+) -> bool:
+    """Stage a replacement after verifying ownership, then recheck before writing."""
+    directory = bundle_directory(repository)
+    old_manifest: BundleManifest | None = None
+    try:
+        if directory.exists() and any(directory.iterdir()):
+            old_manifest = verify_existing()
+        payload, manifest = _source_payload(repository_components(repository))
+        if old_manifest == manifest:
+            return False
+        payload[MANIFEST_NAME] = (
+            json.dumps(manifest, indent=2, sort_keys=True) + "\n"
+        ).encode("utf-8")
+        directory.mkdir(parents=True, exist_ok=True)
+        with tempfile.TemporaryDirectory(
+            prefix=".h2h-dev-tools-", dir=directory.parent
+        ) as temporary:
+            staging = Path(temporary)
+            for name, content in payload.items():
+                (staging / name).write_bytes(content)
+            # Recheck existing authority after preparing the replacement payload.
+            if old_manifest is not None:
+                if verify_existing() != old_manifest:
+                    raise BundleError("Bundle changed while preparing its update")
+            elif any(directory.iterdir()):
+                raise BundleError("Initial bundle directory is no longer empty")
+            bundle_directory(repository)
+            for cache in cache_files(
+                directory,
+                frozenset(old_manifest["files"]) if old_manifest else frozenset(),
+            ):
+                cache.unlink()
+            cache_directory = directory / "__pycache__"
+            if cache_directory.exists():
+                cache_directory.rmdir()
+            for name in sorted(manifest["files"]):
+                os.replace(staging / name, directory / name)
+            if old_manifest is not None:
+                for name in sorted(set(old_manifest["files"]) - set(manifest["files"])):
+                    (directory / name).unlink()
+            os.replace(staging / MANIFEST_NAME, directory / MANIFEST_NAME)
+        verify_bundle(repository)
+    except OSError as error:
+        raise BundleError(f"Cannot synchronize source bundle: {error}") from error
+    return True

h2h_dev_tools/bundle_verify.py

@@ -0,0 +1,255 @@
+"""Verify the complete, committed source bundle without external dependencies."""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import re
+import stat
+import sys
+import tomllib
+from pathlib import Path
+from typing import TypedDict, cast
+
+BUNDLE_DIRECTORY = Path("scripts/_shared/h2h_dev_tools")
+MANIFEST_NAME = "manifest.json"
+BASE_FILES = frozenset({"__init__.py", "bundle_verify.py"})
+COMPONENT_FILES: dict[str, frozenset[str]] = {
+    "atomic-files": frozenset({"atomic_files.py"}),
+    "change-scope": frozenset({"change_scope.py"}),
+    "documentation": frozenset({"documentation.py", "change_scope.py"}),
+    "dependencies": frozenset({"dependency_manifest.py", "ci_dependencies.py"}),
+    "dependency-audit": frozenset({"dependency_manifest.py", "dependency_audit.py"}),
+    "version-policy": frozenset({"dependency_manifest.py", "version_policy.py"}),
+    "publish-version": frozenset({"publish_version.py"}),
+    "process": frozenset({"process.py"}),
+    "distribution-check": frozenset({"distribution_check.py"}),
+    "offline-wheel": frozenset({"offline_wheel.py"}),
+    "formal": frozenset({"formal.py"}),
+    "primary-branch": frozenset({"primary-branch.sh"}),
+    "git-flow": frozenset({"primary-branch.sh", "git-flow-merge.sh"}),
+    "hooks": frozenset({"primary-branch.sh", "install-git-hooks.sh"}),
+    "environment": frozenset({"rebuild-env.sh"}),
+}
+
+
+def component_files(components: object) -> frozenset[str]:
+    """Resolve a canonical component selection to its complete dependency closure."""
+    if not isinstance(components, list) or not all(
+        isinstance(c, str) for c in components
+    ):
+        raise BundleError("Bundle components must be a list of names")
+    if (
+        components != sorted(set(components))
+        or not set(components) <= COMPONENT_FILES.keys()
+    ):
+        raise BundleError("Bundle components must be unique, sorted, known names")
+    return BASE_FILES.union(*(COMPONENT_FILES[c] for c in components))
+
+
+def repository_components(repository: Path) -> list[str]:
+    """Require explicit selection; syncing never guesses consumer requirements."""
+    try:
+        document = tomllib.loads(
+            regular_bytes(repository / "pyproject.toml").decode("utf-8")
+        )
+        components = document["tool"]["h2h-dev-tools"]["components"]
+    except (KeyError, UnicodeError, tomllib.TOMLDecodeError) as error:
+        raise BundleError(
+            "Declare [tool.h2h-dev-tools].components in pyproject.toml"
+        ) from error
+    if not isinstance(components, list) or not all(
+        isinstance(c, str) for c in components
+    ):
+        raise BundleError("Configured components must be a list of names")
+    if len(components) != len(set(components)):
+        raise BundleError("Configured components contain duplicates")
+    result = sorted(components)
+    component_files(result)
+    return result
+
+
+_SHA256 = re.compile(r"[0-9a-f]{64}")
+_VERSION = re.compile(r"(?:0|[1-9][0-9]*)\.(?:0|[1-9][0-9]*)\.(?:0|[1-9][0-9]*)")
+_CACHE_NAME = re.compile(
+    r"(?P<module>[A-Za-z_][A-Za-z_0-9]*)\.cpython-[0-9]+(?:\.opt-[12])?\.pyc"
+)
+
+
+class BundleError(RuntimeError):
+    """A generated source bundle cannot be verified or safely replaced."""
+
+
+class BundleManifest(TypedDict):
+    """The exact source payload and its producing toolkit release."""
+
+    schema_version: int
+    components: list[str]
+    toolkit_name: str
+    toolkit_version: str
+    payload_sha256: str
+    files: dict[str, str]
+
+
+def payload_digest(files: dict[str, str]) -> str:
+    """Fingerprint the named source bytes, not an unobserved wheel archive."""
+    encoded = json.dumps(files, sort_keys=True, separators=(",", ":")).encode("utf-8")
+    return hashlib.sha256(encoded).hexdigest()
+
+
+def bundle_directory(repository: Path) -> Path:
+    """Reject symlinks in every repository-relative managed directory."""
+    root = repository.absolute()
+    try:
+        if not stat.S_ISDIR(root.lstat().st_mode):
+            raise BundleError(f"Repository must be a real directory: {root}")
+        current = root
+        for component in BUNDLE_DIRECTORY.parts:
+            current /= component
+            try:
+                mode = current.lstat().st_mode
+            except FileNotFoundError:
+                continue
+            if not stat.S_ISDIR(mode):
+                raise BundleError(
+                    f"Managed bundle path must be a real directory: {current}"
+                )
+    except OSError as error:
+        raise BundleError(f"Cannot inspect bundle directories: {error}") from error
+    return root / BUNDLE_DIRECTORY
+
+
+def _reject_duplicate_keys(pairs: list[tuple[str, object]]) -> dict[str, object]:
+    result: dict[str, object] = {}
+    for key, value in pairs:
+        if key in result:
+            raise BundleError(f"Duplicate manifest key: {key}")
+        result[key] = value
+    return result
+
+
+def regular_bytes(path: Path) -> bytes:
+    """Read a generated regular file without accepting a symlink entry."""
+    try:
+        if not stat.S_ISREG(path.lstat().st_mode):
+            raise BundleError(f"Bundle entry must be a regular file: {path}")
+        return path.read_bytes()
+    except OSError as error:
+        raise BundleError(f"Cannot read bundle file {path}: {error}") from error
+
+
+def _read_manifest(path: Path) -> BundleManifest:
+    try:
+        document: object = json.loads(
+            regular_bytes(path), object_pairs_hook=_reject_duplicate_keys
+        )
+    except (UnicodeError, json.JSONDecodeError) as error:
+        raise BundleError(f"Invalid bundle manifest: {error}") from error
+    return validate_manifest(document)
+
+
+def validate_manifest(document: object) -> BundleManifest:
+    """Accept only the complete schema and safe, explicitly owned filenames."""
+    if not isinstance(document, dict) or set(document) != {
+        "schema_version",
+        "components",
+        "toolkit_name",
+        "toolkit_version",
+        "payload_sha256",
+        "files",
+    }:
+        raise BundleError("Bundle manifest fields do not match schema 2")
+    if type(document["schema_version"]) is not int or document["schema_version"] != 2:
+        raise BundleError("Unsupported bundle manifest schema")
+    if document["toolkit_name"] != "h2h-dev-tools":
+        raise BundleError("Bundle manifest belongs to another toolkit")
+    version = document["toolkit_version"]
+    if not isinstance(version, str) or _VERSION.fullmatch(version) is None:
+        raise BundleError("Bundle toolkit version must be X.Y.Z")
+    files = document["files"]
+    if not isinstance(files, dict) or set(files) != component_files(
+        document["components"]
+    ):
+        raise BundleError("Bundle manifest must declare the complete source file set")
+    if not all(
+        isinstance(value, str) and _SHA256.fullmatch(value) for value in files.values()
+    ):
+        raise BundleError("Invalid source file SHA-256 in bundle manifest")
+    if document["payload_sha256"] != payload_digest(files):
+        raise BundleError("Bundle payload fingerprint does not match its file manifest")
+    return cast(BundleManifest, document)
+
+
+def cache_files(directory: Path, files: frozenset[str]) -> tuple[Path, ...]:
+    """Identify disposable CPython caches without accepting other extra content."""
+    cache = directory / "__pycache__"
+    try:
+        try:
+            mode = cache.lstat().st_mode
+        except FileNotFoundError:
+            return ()
+        if not stat.S_ISDIR(mode):
+            raise BundleError("Bundle __pycache__ must be a real directory")
+        entries = tuple(cache.iterdir())
+        for entry in entries:
+            match = _CACHE_NAME.fullmatch(entry.name)
+            if (
+                match is None
+                or f"{match['module']}.py" not in files
+                or not stat.S_ISREG(entry.lstat().st_mode)
+            ):
+                raise BundleError(f"Unknown or nonregular bundle cache entry: {entry}")
+        return entries
+    except OSError as error:
+        raise BundleError(f"Cannot inspect bundle bytecode caches: {error}") from error
+
+
+def verify_bundle(repository: Path, *, check_selection: bool = True) -> BundleManifest:
+    """Prove that each declared file matches and that no extra entry exists."""
+    directory = bundle_directory(repository)
+    manifest = _read_manifest(directory / MANIFEST_NAME)
+    if check_selection and manifest["components"] != repository_components(repository):
+        raise BundleError("Bundle component selection is stale; run explicit sync")
+    return verify_payload(repository, manifest)
+
+
+def verify_payload(repository: Path, manifest: BundleManifest) -> BundleManifest:
+    """Verify an already validated manifest against the complete managed directory."""
+    directory = bundle_directory(repository)
+    try:
+        actual = {entry.name for entry in directory.iterdir()}
+    except OSError as error:
+        raise BundleError(f"Cannot inspect bundle file closure: {error}") from error
+    files = frozenset(manifest["files"])
+    expected = files | {MANIFEST_NAME}
+    cache_files(directory, files)
+    actual.discard("__pycache__")
+    if actual != expected:
+        raise BundleError(
+            f"Bundle file closure mismatch; missing={sorted(expected - actual)}, "
+            f"extra={sorted(actual - expected)}"
+        )
+    for name, expected_hash in manifest["files"].items():
+        actual_hash = hashlib.sha256(regular_bytes(directory / name)).hexdigest()
+        if actual_hash != expected_hash:
+            raise BundleError(f"Generated source was modified: {name}")
+    return manifest
+
+
+def main(arguments: list[str] | None = None) -> int:
+    """Provide a standalone consumer-side verification entry point."""
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--repository", required=True, type=Path)
+    options = parser.parse_args(arguments)
+    try:
+        manifest = verify_bundle(options.repository)
+    except BundleError as error:
+        print(f"h2h-dev-tools: {error}", file=sys.stderr)
+        return 1
+    print(f"Verified h2h-dev-tools {manifest['toolkit_version']} source bundle.")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

h2h_dev_tools/change_scope.py

@@ -0,0 +1,167 @@
+#!/usr/bin/env python3
+"""Classify an exact Git tree difference for documentation-only checks."""
+
+from __future__ import annotations
+
+import argparse
+import re
+import subprocess
+import sys
+from pathlib import Path, PurePosixPath
+from typing import Literal
+
+ChangeScope = Literal["documentation", "full"]
+_DOCUMENT_PATHS = frozenset(
+    {"README.md", "benchmarks/README.md", "verification/README.md"}
+)
+_OBJECT_ID = re.compile(r"[0-9a-f]{40}(?:[0-9a-f]{24})?")
+
+
+class ChangeScopeError(RuntimeError):
+    """The exact change set could not be established safely."""
+
+
+def git_output(root: Path, *arguments: str) -> bytes:
+    """Read Git output without interpreting filenames as lines or shell code."""
+
+    try:
+        result = subprocess.run(
+            ("git", *arguments),
+            cwd=root,
+            check=True,
+            capture_output=True,
+            timeout=60,
+        )
+    except (OSError, subprocess.SubprocessError) as error:
+        detail = (
+            (error.stderr or error.stdout).decode("utf-8", errors="replace").strip()
+            if isinstance(error, subprocess.CalledProcessError)
+            else str(error)
+        )
+        raise ChangeScopeError(f"Git operation failed: {detail}") from error
+    return result.stdout
+
+
+def resolve_tree(root: Path, revision: str) -> str:
+    """Resolve a commit or tree to one immutable tree object ID."""
+
+    output = git_output(
+        root, "rev-parse", "--verify", "--end-of-options", f"{revision}^{{tree}}"
+    )
+    try:
+        tree = output.decode("ascii").strip()
+    except UnicodeError as error:
+        raise ChangeScopeError("Git returned an invalid tree object ID") from error
+    if _OBJECT_ID.fullmatch(tree) is None:
+        raise ChangeScopeError("Git returned an invalid tree object ID")
+    return tree
+
+
+def capture_candidate(root: Path, revision: str | None) -> str:
+    """Capture either the index or an explicitly requested revision."""
+
+    if revision is not None:
+        return resolve_tree(root, revision)
+    try:
+        tree = git_output(root, "write-tree").decode("ascii").strip()
+    except UnicodeError as error:
+        raise ChangeScopeError("Git returned an invalid index tree") from error
+    return resolve_tree(root, tree)
+
+
+def _is_document(path: str) -> bool:
+    parts = PurePosixPath(path).parts
+    if parts and parts[-1].casefold() in {"agents.md", "claude.md"}:
+        return False
+    return path in _DOCUMENT_PATHS or (
+        len(parts) >= 2 and parts[0] == "docs" and path.endswith(".md")
+    )
+
+
+def _is_text(root: Path, object_id: str) -> bool:
+    content = git_output(root, "cat-file", "blob", object_id)
+    if b"\0" in content:
+        return False
+    try:
+        content.decode("utf-8")
+    except UnicodeError:
+        return False
+    return True
+
+
+def classify_changes(base: str, candidate: str, root: Path) -> ChangeScope:
+    """Allow only registered, non-executable text documents into the light gate."""
+
+    base_tree = resolve_tree(root, base)
+    candidate_tree = resolve_tree(root, candidate)
+    raw = git_output(
+        root,
+        "diff",
+        "--raw",
+        "--no-renames",
+        "--no-ext-diff",
+        "--no-textconv",
+        "--ignore-submodules=none",
+        "--no-abbrev",
+        "-z",
+        base_tree,
+        candidate_tree,
+        "--",
+    )
+    if not raw:
+        return "full"
+    fields = raw.split(b"\0")
+    if fields.pop() != b"" or len(fields) % 2:
+        raise ChangeScopeError("Malformed NUL-delimited Git difference")
+    for index in range(0, len(fields), 2):
+        try:
+            header = fields[index].decode("ascii").split()
+            path = fields[index + 1].decode("utf-8")
+        except UnicodeError:
+            return "full"
+        if len(header) != 5 or not header[0].startswith(":"):
+            raise ChangeScopeError("Malformed raw Git difference entry")
+        old_mode, new_mode, old_id, new_id, status = header
+        modes = (old_mode[1:], new_mode)
+        expected = {
+            "A": ("000000", "100644"),
+            "M": ("100644", "100644"),
+            "D": ("100644", "000000"),
+        }
+        if not _is_document(path) or modes != expected.get(status):
+            return "full"
+        for mode, object_id in zip(modes, (old_id, new_id), strict=True):
+            if mode != "000000" and not _is_text(root, object_id):
+                return "full"
+    return "documentation"
+
+
+def add_target_arguments(parser: argparse.ArgumentParser) -> None:
+    targets = parser.add_mutually_exclusive_group(required=True)
+    targets.add_argument("--index", action="store_true", help="check the staged tree")
+    targets.add_argument("--candidate", help="check this commit or tree")
+    parser.add_argument("--base", default="HEAD", help="comparison commit or tree")
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    add_target_arguments(parser)
+    arguments = parser.parse_args()
+    root = Path.cwd()
+    base = resolve_tree(root, arguments.base)
+    candidate = capture_candidate(root, arguments.candidate)
+    scope = classify_changes(base, candidate, root)
+    if capture_candidate(root, arguments.candidate) != candidate:
+        raise ChangeScopeError("Candidate changed while classifying its scope")
+    if resolve_tree(root, arguments.base) != base:
+        raise ChangeScopeError("Base changed while classifying the candidate scope")
+    print(scope)
+    return 0
+
+
+if __name__ == "__main__":
+    try:
+        raise SystemExit(main())
+    except ChangeScopeError as error:
+        print(f"check-change-scope: {error}", file=sys.stderr)
+        raise SystemExit(1) from error

h2h_dev_tools/ci_dependencies.py

@@ -0,0 +1,70 @@
+"""Install a CI dependency subset using the project's declared requirements."""
+
+from __future__ import annotations
+
+import argparse
+import re
+import subprocess
+import sys
+import tomllib
+from pathlib import Path
+
+
+def _package_name(requirement: str) -> str:
+    match = re.match(r"[A-Za-z0-9][A-Za-z0-9._-]*", requirement)
+    if match is None:
+        raise ValueError(f"Invalid dependency name: {requirement!r}")
+    return re.sub(r"[-_.]+", "-", match[0]).lower()
+
+
+def requirements_for(
+    manifest: Path, packages: list[str], *, pytest_plugins: bool
+) -> list[str]:
+    with manifest.open("rb") as stream:
+        document = tomllib.load(stream)
+    project = document["project"]
+    declared = [
+        *project.get("dependencies", []),
+        *project.get("optional-dependencies", {}).get("dev", []),
+    ]
+    requirements: list[str] = []
+    for package in packages:
+        matches = [
+            requirement
+            for requirement in declared
+            if _package_name(requirement) == _package_name(package)
+        ]
+        if not matches:
+            raise ValueError(f"Dependency is not declared in {manifest}: {package}")
+        requirements.extend(matches)
+    if pytest_plugins:
+        requirements.extend(
+            document["tool"]["pytest"]["ini_options"]["required_plugins"]
+        )
+    return list(dict.fromkeys(requirements))
+
+
+def main(repository: Path | None = None) -> None:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("packages", nargs="+", help="runtime or dev dependency names")
+    parser.add_argument(
+        "--pytest-plugins",
+        action="store_true",
+        help="also install every plugin required by the repository pytest settings",
+    )
+    arguments = parser.parse_args()
+    manifest = (Path.cwd() if repository is None else repository) / "pyproject.toml"
+    try:
+        requirements = requirements_for(
+            manifest, arguments.packages, pytest_plugins=arguments.pytest_plugins
+        )
+    except (KeyError, OSError, ValueError) as error:
+        parser.error(str(error))
+    subprocess.run(
+        [sys.executable, "-m", "pip", "install", "--upgrade", *requirements],
+        check=True,
+    )
+
+
+if __name__ == "__main__":
+    main()