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

h2h_dev_tools/dependency_audit.py

@@ -0,0 +1,220 @@
+#!/usr/bin/env python3
+"""Audit every direct Python and Node dependency and write a review receipt."""
+
+from __future__ import annotations
+
+import argparse
+import datetime as dt
+import hashlib
+import json
+import subprocess
+import sys
+import tomllib
+import urllib.error
+import urllib.parse
+import urllib.request
+from functools import cache
+from pathlib import Path
+from typing import Any, cast
+
+from packaging.requirements import Requirement
+from packaging.specifiers import SpecifierSet
+from packaging.version import Version
+
+from .dependency_manifest import dependency_manifest
+
+
+def _python_requirements(document: dict[str, Any]) -> list[tuple[str, str]]:
+    project = document.get("project", {})
+    grouped: list[tuple[str, list[str]]] = [
+        ("build", document.get("build-system", {}).get("requires", [])),
+        ("runtime", project.get("dependencies", [])),
+    ]
+    grouped.extend(
+        (f"optional:{name}", requirements)
+        for name, requirements in project.get("optional-dependencies", {}).items()
+    )
+    grouped.extend(
+        (f"group:{name}", requirements)
+        for name, requirements in document.get("dependency-groups", {}).items()
+    )
+    return [
+        (group, requirement)
+        for group, requirements in grouped
+        for requirement in requirements
+        if isinstance(requirement, str)
+    ]
+
+
+@cache
+def _pypi_json(name: str) -> dict[str, Any]:
+    normalized = urllib.parse.quote(name, safe="")
+    request = urllib.request.Request(
+        f"https://pypi.org/pypi/{normalized}/json",
+        headers={"User-Agent": "h2h-dependency-audit/1"},
+    )
+    with urllib.request.urlopen(request, timeout=30) as response:
+        payload = json.load(response)
+    if not isinstance(payload, dict):
+        raise ValueError(f"invalid PyPI response for {name}")
+    return cast(dict[str, Any], payload)
+
+
+def _supports_python_314(files: list[dict[str, Any]]) -> bool:
+    for file in files:
+        if file.get("yanked"):
+            continue
+        requires_python = file.get("requires_python")
+        if not requires_python or Version("3.14") in SpecifierSet(requires_python):
+            return True
+    return False
+
+
+def _release_notes_url(info: dict[str, Any]) -> str | None:
+    project_urls = info.get("project_urls")
+    if not isinstance(project_urls, dict):
+        return None
+    for label, url in project_urls.items():
+        normalized = str(label).casefold().replace("_", " ").replace("-", " ")
+        if normalized in {
+            "changelog",
+            "changes",
+            "history",
+            "release notes",
+        } and isinstance(url, str):
+            return url
+    return None
+
+
+def _audit_python(group: str, declared: str) -> dict[str, Any]:
+    requirement = Requirement(declared)
+    if requirement.url is not None:
+        return {
+            "declared": declared,
+            "group": group,
+            "latest": None,
+            "latest_satisfies": None,
+            "name": requirement.name,
+            "note": "direct URL/ref requires manual upstream review",
+            "python_3_14": None,
+        }
+    payload = _pypi_json(requirement.name)
+    info = payload["info"]
+    latest = str(info["version"])
+    return {
+        "declared": declared,
+        "group": group,
+        "latest": latest,
+        "latest_satisfies": Version(latest) in requirement.specifier,
+        "name": requirement.name,
+        "python_3_14": _supports_python_314(payload["releases"].get(latest, [])),
+        "registry_url": info.get("package_url"),
+        "release_notes": _release_notes_url(info),
+        "url": info.get("project_url") or info.get("package_url"),
+    }
+
+
+def _npm_view_version(specification: str) -> str | list[str]:
+    completed = subprocess.run(
+        ("npm", "view", specification, "version", "--json"),
+        check=True,
+        stdout=subprocess.PIPE,
+        text=True,
+    )
+    value = json.loads(completed.stdout)
+    if not isinstance(value, (str, list)) or (
+        isinstance(value, list)
+        and not all(isinstance(version, str) for version in value)
+    ):
+        raise ValueError(
+            f"invalid latest version or matching versions from npm for {specification}"
+        )
+    return cast(str | list[str], value)
+
+
+def _audit_node(name: str, declared: str) -> dict[str, Any]:
+    latest_value = _npm_view_version(name)
+    if not isinstance(latest_value, str) or not latest_value:
+        raise ValueError(f"invalid latest version from npm for {name}")
+    matching_value = _npm_view_version(f"{name}@{declared}")
+    matching_versions = (
+        [matching_value] if isinstance(matching_value, str) else matching_value
+    )
+    return {
+        "declared": declared,
+        "latest": latest_value,
+        "latest_satisfies": latest_value in matching_versions,
+        "name": name,
+        "registry_url": f"https://www.npmjs.com/package/{name}",
+    }
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--review-note", required=True)
+    parser.add_argument(
+        "--output",
+        default=".release/dependency-audit.json",
+        type=Path,
+    )
+    arguments = parser.parse_args()
+    if not arguments.review_note.strip():
+        parser.error("--review-note must not be empty")
+
+    with Path("pyproject.toml").open("rb") as stream:
+        document = tomllib.load(stream)
+    package = json.loads(Path("package.json").read_text())
+    python_audit = [
+        _audit_python(group, requirement)
+        for group, requirement in _python_requirements(document)
+    ]
+    node_audit = [
+        _audit_node(name, declared)
+        for name, declared in package.get("devDependencies", {}).items()
+    ]
+    receipt = {
+        "checked_at": dt.datetime.now(dt.UTC).replace(microsecond=0).isoformat(),
+        "manifest_sha256": hashlib.sha256(
+            dependency_manifest(document, package)
+        ).hexdigest(),
+        "node": node_audit,
+        "project_version": document["project"]["version"],
+        "python": python_audit,
+        "review": {
+            "note": arguments.review_note.strip(),
+            "status": "reviewed",
+        },
+        "schema": "h2h.dependency-audit.v1",
+    }
+    arguments.output.parent.mkdir(parents=True, exist_ok=True)
+    arguments.output.write_text(
+        json.dumps(receipt, ensure_ascii=False, indent=2, sort_keys=True) + "\n"
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    try:
+        raise SystemExit(main())
+    except urllib.error.HTTPError as error:
+        print(
+            f"audit-dependencies: registry HTTP {error.code} for "
+            f"{error.url}: {error.reason}",
+            file=sys.stderr,
+        )
+        raise SystemExit(1) from error
+    except urllib.error.URLError as error:
+        print(
+            f"audit-dependencies: registry request failed: {error.reason}",
+            file=sys.stderr,
+        )
+        raise SystemExit(1) from error
+    except json.JSONDecodeError as error:
+        print(
+            f"audit-dependencies: registry returned invalid JSON: {error}",
+            file=sys.stderr,
+        )
+        raise SystemExit(1) from error
+    except (OSError, subprocess.CalledProcessError, ValueError) as error:
+        print(f"audit-dependencies: {type(error).__name__}: {error}", file=sys.stderr)
+        raise SystemExit(1) from error

h2h_dev_tools/dependency_manifest.py

@@ -0,0 +1,23 @@
+"""Canonical dependency bytes shared by audit creation and verification."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+
+def dependency_manifest(document: dict[str, Any], package: dict[str, Any]) -> bytes:
+    project = document.get("project", {})
+    manifest = {
+        "build": document.get("build-system", {}).get("requires", []),
+        "dependency-groups": document.get("dependency-groups", {}),
+        "optional": project.get("optional-dependencies", {}),
+        "runtime": project.get("dependencies", []),
+        "node-dev": package.get("devDependencies", {}),
+    }
+    return json.dumps(
+        manifest,
+        ensure_ascii=False,
+        sort_keys=True,
+        separators=(",", ":"),
+    ).encode()

h2h_dev_tools/distribution_check.py

@@ -0,0 +1,70 @@
+"""Verify installed requirements and wheel RECORD/import origins."""
+
+from __future__ import annotations
+
+import importlib
+import json
+import sys
+from importlib.metadata import Distribution, PackageNotFoundError, distribution
+from pathlib import Path
+
+from packaging.requirements import Requirement
+
+
+def check_runtime_requirements(
+    package: Distribution, *, prereleases: bool | None = None
+) -> dict[str, str]:
+    selected: dict[str, str] = {}
+    for raw in package.requires or ():
+        requirement = Requirement(raw)
+        if requirement.marker is not None and not requirement.marker.evaluate(
+            {"extra": ""}
+        ):
+            continue
+        try:
+            dependency = distribution(requirement.name)
+        except PackageNotFoundError as error:
+            raise RuntimeError(
+                f"{package.metadata['Name']} requires {requirement}; package is missing"
+            ) from error
+        if not requirement.specifier.contains(
+            dependency.version, prereleases=prereleases
+        ):
+            raise RuntimeError(
+                f"{package.metadata['Name']} requires {requirement}; "
+                f"installed {requirement.name}=={dependency.version} "
+                f"does not satisfy {requirement}"
+            )
+        selected[requirement.name] = dependency.version
+    return selected
+
+
+def check_wheel_origin(project: str, module_name: str, *, local: bool) -> str:
+    package = distribution(project)
+    module = importlib.import_module(module_name)
+    if module.__file__ is None:
+        raise RuntimeError(f"{project} has no import origin")
+    actual = Path(module.__file__).resolve()
+    record_name = module_name.replace(".", "/") + "/__init__.py"
+    expected = Path(str(package.locate_file(record_name))).resolve()
+    if actual != expected:
+        raise RuntimeError(
+            f"{project} import disagrees with installed metadata: {actual}"
+        )
+    if package.files is None or not any(
+        str(item) == record_name for item in package.files
+    ):
+        raise RuntimeError(f"{project} has no installed package RECORD")
+    direct = json.loads(package.read_text("direct_url.json") or "{}")
+    if direct.get("dir_info", {}).get("editable", False):
+        raise RuntimeError(
+            f"{project} must come from a wheel, not an editable checkout"
+        )
+    if local and (
+        not actual.is_relative_to(Path(sys.prefix).resolve())
+        or not Path(str(package.locate_file("")))
+        .resolve()
+        .is_relative_to(Path(sys.prefix).resolve())
+    ):
+        raise RuntimeError(f"{project} must be installed inside the smoke environment")
+    return str(actual)

h2h_dev_tools/documentation.py

@@ -0,0 +1,175 @@
+#!/usr/bin/env python3
+"""Check documentation from an exact Git snapshot without program checks."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import posixpath
+import subprocess
+import sys
+import tomllib
+from pathlib import Path, PurePosixPath
+from tempfile import TemporaryDirectory
+
+from .change_scope import (
+    ChangeScopeError,
+    add_target_arguments,
+    capture_candidate,
+    classify_changes,
+    git_output,
+    resolve_tree,
+)
+
+_CONFIG = ".markdownlint-cli2.jsonc"
+
+
+def _regular_blob(root: Path, tree: str, path: str) -> bytes | None:
+    raw = git_output(root, "--literal-pathspecs", "ls-tree", "-z", tree, "--", path)
+    if not raw:
+        return None
+    entries = raw.split(b"\0")
+    header, separator, name = entries[0].partition(b"\t")
+    fields = header.split()
+    if (
+        len(entries) != 2
+        or entries[-1] != b""
+        or not separator
+        or name != path.encode("utf-8")
+        or len(fields) != 3
+        or fields[0] not in (b"100644", b"100755")
+        or fields[1] != b"blob"
+    ):
+        raise ChangeScopeError(
+            f"Documentation metadata requires a regular file: {path}"
+        )
+    return git_output(root, "cat-file", "blob", fields[2].decode("ascii"))
+
+
+def _check_readme_reference(root: Path, tree: str) -> None:
+    content = _regular_blob(root, tree, "pyproject.toml")
+    if content is None:
+        return
+    try:
+        document = tomllib.loads(content.decode("utf-8"))
+    except (UnicodeError, tomllib.TOMLDecodeError) as error:
+        raise ChangeScopeError(
+            f"Cannot read candidate documentation metadata: {error}"
+        ) from error
+    project = document.get("project", {})
+    if not isinstance(project, dict):
+        raise ChangeScopeError("Candidate project metadata must be a table")
+    readme: object = project.get("readme")
+    if readme is None:
+        return
+    if isinstance(readme, dict):
+        if set(readme) - {"file", "text", "content-type"}:
+            raise ChangeScopeError("Unsupported project.readme table fields")
+        if ("file" in readme) == ("text" in readme):
+            raise ChangeScopeError(
+                "project.readme requires exactly one of file or text"
+            )
+        content_type = readme.get("content-type")
+        if not isinstance(content_type, str) or not content_type.strip():
+            raise ChangeScopeError("project.readme table requires a content-type")
+        if "text" in readme:
+            if not isinstance(readme["text"], str):
+                raise ChangeScopeError("project.readme text must be a string")
+            return
+        readme = readme["file"]
+    if not isinstance(readme, str) or not readme:
+        raise ChangeScopeError("project.readme file must be a nonempty relative path")
+    path = posixpath.normpath(readme)
+    if path in (".", "..") or path.startswith(("/", "../")):
+        raise ChangeScopeError(
+            "project.readme file must stay inside the candidate tree"
+        )
+    if _regular_blob(root, tree, path) is None:
+        raise ChangeScopeError(f"Missing project.readme file in candidate: {readme}")
+
+
+def _export_documents(root: Path, tree: str, destination: Path) -> None:
+    config_found = False
+    directories: dict[tuple[int, int], tuple[str, ...]] = {}
+    for entry in git_output(root, "ls-tree", "-r", "-z", tree).split(b"\0"):
+        if not entry:
+            continue
+        header, separator, raw_path = entry.partition(b"\t")
+        if not separator:
+            raise ChangeScopeError("Malformed Git tree entry")
+        fields = header.split()
+        if len(fields) != 3:
+            raise ChangeScopeError("Malformed Git tree entry header")
+        mode, kind, object_id = fields
+        path = os.fsdecode(raw_path)
+        if path != _CONFIG and not path.endswith(".md"):
+            continue
+        if mode not in (b"100644", b"100755") or kind != b"blob":
+            if path == _CONFIG:
+                raise ChangeScopeError("Markdown configuration must be a regular file")
+            continue
+        parts = PurePosixPath(path).parts
+        if not parts or PurePosixPath(path).is_absolute() or ".." in parts:
+            raise ChangeScopeError("Unsafe path in documentation tree")
+        output = destination.joinpath(*parts)
+        try:
+            parent = destination
+            for depth, component in enumerate(parts[:-1], start=1):
+                parent /= component
+                parent.mkdir(exist_ok=True)
+                metadata = parent.stat()
+                identity = (metadata.st_dev, metadata.st_ino)
+                previous = directories.setdefault(identity, parts[:depth])
+                if previous != parts[:depth]:
+                    raise ChangeScopeError(
+                        f"Colliding documentation directories: {path!r}"
+                    )
+            with output.open("xb") as stream:
+                stream.write(
+                    git_output(root, "cat-file", "blob", object_id.decode("ascii"))
+                )
+        except (FileExistsError, IsADirectoryError, NotADirectoryError) as error:
+            raise ChangeScopeError(
+                f"Colliding documentation paths on this filesystem: {path!r}"
+            ) from error
+        config_found |= path == _CONFIG
+    if not config_found:
+        raise ChangeScopeError(f"Candidate has no regular {_CONFIG}")
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    add_target_arguments(parser)
+    arguments = parser.parse_args()
+    root = Path.cwd()
+    candidate = capture_candidate(root, arguments.candidate)
+    base = resolve_tree(root, arguments.base)
+    if classify_changes(base, candidate, root) != "documentation":
+        raise ChangeScopeError("Candidate is not a documentation-only change")
+    git_output(root, "diff", "--check", "--no-ext-diff", base, candidate, "--")
+    _check_readme_reference(root, candidate)
+    tool_name = "markdownlint-cli2.cmd" if os.name == "nt" else "markdownlint-cli2"
+    executable = root / "node_modules" / ".bin" / tool_name
+    if not executable.is_file() or not os.access(executable, os.X_OK):
+        raise ChangeScopeError(f"Missing repository-local Markdown tool: {executable}")
+    with TemporaryDirectory(prefix="h2h-docs-check-") as directory:
+        snapshot = Path(directory)
+        _export_documents(root, candidate, snapshot)
+        try:
+            subprocess.run((str(executable),), cwd=snapshot, check=True)
+        except (OSError, subprocess.SubprocessError) as error:
+            raise ChangeScopeError(f"Markdown check failed: {error}") from error
+    if capture_candidate(root, arguments.candidate) != candidate:
+        raise ChangeScopeError("Candidate changed while checking documentation")
+    if resolve_tree(root, arguments.base) != base:
+        raise ChangeScopeError("Base changed while checking documentation")
+    print(f"Documentation checks passed for tree {candidate}")
+    return 0
+
+
+if __name__ == "__main__":
+    try:
+        raise SystemExit(main())
+    except (ChangeScopeError, OSError, UnicodeError) as error:
+        print(f"check-docs: {error}", file=sys.stderr)
+        raise SystemExit(1) from error