code-standards 7.0.0__py3-none-any.whl

sarj_standards/libs/release/registry.py

@@ -0,0 +1,271 @@
+from __future__ import annotations
+
+import argparse
+from dataclasses import dataclass
+from datetime import timedelta
+import json
+import math
+from pathlib import Path
+import re
+import sys
+import time
+import tomllib
+from types import MappingProxyType
+from typing import TYPE_CHECKING, ClassVar, Final, Literal, Protocol
+from urllib.error import HTTPError
+from urllib.parse import quote
+from urllib.request import Request, urlopen
+
+from packaging.utils import InvalidSdistFilename, InvalidWheelFilename, parse_sdist_filename, parse_wheel_filename
+from packaging.version import InvalidVersion, Version
+from pydantic import BaseModel, ConfigDict, Field
+
+from sarj_standards.libs.release._values import is_object_dict, is_object_list, string_object_dict
+from sarj_standards.libs.release.tags import RELEASE_TARGETS, read_manifest_version
+
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Mapping, Sequence
+
+
+RegistryKind = Literal["npm", "pypi"]
+
+
+@dataclass(frozen=True, slots=True, order=True)
+class RegistryRequirement:
+    registry: RegistryKind
+    name: str
+    version: str
+
+
+class _PypiSimpleFile(BaseModel):
+    model_config: ClassVar[ConfigDict] = ConfigDict(extra="ignore", strict=True)
+
+    filename: str = Field(min_length=1)
+
+
+class _PypiSimpleResponse(BaseModel):
+    model_config: ClassVar[ConfigDict] = ConfigDict(extra="ignore", strict=True)
+
+    files: tuple[_PypiSimpleFile, ...]
+
+
+class PublicationChecker(Protocol):
+    def __call__(self, requirement: RegistryRequirement, /) -> bool: ...
+
+
+class _Args(argparse.Namespace):
+    root: Path = Path()
+    attempts: int = 6
+    delay: timedelta = timedelta(seconds=10)
+
+
+_TARGET_PACKAGES: Final[Mapping[str, tuple[RegistryKind, str]]] = MappingProxyType(
+    {
+        "typescript": ("npm", "@sarj/eslint-plugin"),
+        "bootstrap": ("pypi", "sarj-standards-bootstrap"),
+        "python": ("pypi", "sarj-python-lint"),
+        "sql": ("pypi", "sarj-sql-lint"),
+        "iac": ("pypi", "sarj-iac-lint"),
+        "standards": ("pypi", "code-standards"),
+        "tsconfig": ("npm", "@sarj/tsconfig"),
+        "docs-ui": ("npm", "@sarj/docs-ui"),
+    }
+)
+_EXACT_DEPENDENCY = re.compile(r"^(?P<name>[A-Za-z0-9_.-]+)==(?P<version>[^;\s]+)$")
+_HTTP_OK = 200
+_HTTP_NOT_FOUND = 404
+
+
+def target_requirement(root: Path, target_name: str) -> RegistryRequirement:
+    target = RELEASE_TARGETS.get(target_name)
+    package = _TARGET_PACKAGES.get(target_name)
+    if target is None or package is None:
+        msg = f"unsupported release target: {target_name}"
+        raise ValueError(msg)
+    registry, name = package
+    version = read_manifest_version(root.resolve() / target.manifest, target.format)
+    return RegistryRequirement(registry, name, version)
+
+
+def publication_exists(requirement: RegistryRequirement) -> bool:
+    if requirement.registry == "pypi":
+        # uv and pip resolve through the Simple API, so version JSON visibility alone does not make a wheel resolvable.
+        url = f"https://pypi.org/simple/{quote(requirement.name, safe='')}/"
+        accept = "application/vnd.pypi.simple.v1+json"
+    else:
+        url = f"https://registry.npmjs.org/{quote(requirement.name, safe='')}/{quote(requirement.version, safe='')}"
+        accept = "application/json"
+    request = Request(  # ruff: ignore[suspicious-url-open-usage] -- URL is constructed only from fixed HTTPS registry origins.
+        url, headers={"Accept": accept}
+    )
+    try:
+        return _request_publication(request, requirement)
+    except HTTPError as exc:
+        if exc.code == _HTTP_NOT_FOUND:
+            return False
+        raise
+
+
+def _request_publication(request: Request, requirement: RegistryRequirement) -> bool:
+    with urlopen(request, timeout=15) as response:  # ruff: ignore[suspicious-url-open-usage]  # pyright: ignore[reportAny] -- fixed registry origins
+        if response.status != _HTTP_OK:  # pyright: ignore[reportAny]
+            return False
+        if requirement.registry == "npm":
+            return True
+        payload: bytes = response.read()  # pyright: ignore[reportAny] -- urllib response is untyped.
+        document = _PypiSimpleResponse.model_validate_json(payload)
+    return any(_pypi_filename_has_version(item.filename, requirement.version) for item in document.files)
+
+
+def _pypi_filename_has_version(filename: str, version: str) -> bool:
+    try:
+        expected = Version(version)
+        if filename.endswith(".whl"):
+            _name, actual, _build, _tags = parse_wheel_filename(filename)
+        else:
+            _name, actual = parse_sdist_filename(filename)
+    except InvalidSdistFilename, InvalidVersion, InvalidWheelFilename:
+        return False
+    return actual == expected
+
+
+def require_publication(
+    requirement: RegistryRequirement,
+    *,
+    checker: PublicationChecker = publication_exists,
+) -> None:
+    if checker(requirement):
+        return
+    msg = f"{requirement.registry} publication is unavailable: {requirement.name}@{requirement.version}"
+    raise ValueError(msg)
+
+
+def lint_config_requirements(root: Path) -> tuple[RegistryRequirement, ...]:
+    resolved = root.resolve()
+    pyproject = resolved / "packages/standards/pyproject.toml"
+    try:
+        with pyproject.open("rb") as stream:
+            parsed: object = tomllib.load(stream)
+    except (OSError, tomllib.TOMLDecodeError) as exc:
+        msg = f"could not read compatibility-bundle manifest {pyproject}: {exc}"
+        raise ValueError(msg) from exc
+    project = string_object_dict(parsed, label="standards manifest")
+    project_table = project.get("project")
+    if not is_object_dict(project_table):
+        msg = f"{pyproject} has no project table"
+        raise ValueError(msg)
+    dependencies = string_object_dict(project_table, label="standards project").get("dependencies")
+    if not is_object_list(dependencies):
+        msg = f"{pyproject} has no dependency list"
+        raise ValueError(msg)
+    requirements: list[RegistryRequirement] = []
+    for dependency in dependencies:
+        if not isinstance(dependency, str) or not dependency.startswith("sarj-"):
+            continue
+        match = _EXACT_DEPENDENCY.fullmatch(dependency)
+        if match is None:
+            msg = f"compatibility-bundle sibling must use an exact pin: {dependency}"
+            raise ValueError(msg)
+        requirements.append(RegistryRequirement("pypi", match["name"], match["version"]))
+
+    peers_path = resolved / "packages/standards/src/sarj_standards/configs/eslint.peers.json"
+    try:
+        peers_value: object = json.loads(peers_path.read_text(encoding="utf-8"))  # pyright: ignore[reportAny]
+    except (OSError, json.JSONDecodeError) as exc:
+        msg = f"could not read compatibility-bundle peers {peers_path}: {exc}"
+        raise ValueError(msg) from exc
+    peers = string_object_dict(peers_value, label="ESLint peer manifest").get("peers")
+    if not is_object_dict(peers):
+        msg = f"{peers_path} has no peers object"
+        raise ValueError(msg)
+    plugin_version = string_object_dict(peers, label="ESLint peers").get("@sarj/eslint-plugin")
+    if not isinstance(plugin_version, str) or not plugin_version:
+        msg = f"{peers_path} has no exact @sarj/eslint-plugin version"
+        raise ValueError(msg)
+    requirements.append(RegistryRequirement("npm", "@sarj/eslint-plugin", plugin_version))
+    return tuple(sorted(requirements))
+
+
+def require_lint_config_dependencies(
+    root: Path,
+    *,
+    checker: PublicationChecker = publication_exists,
+) -> tuple[RegistryRequirement, ...]:
+    requirements = lint_config_requirements(root)
+    for requirement in requirements:
+        require_publication(requirement, checker=checker)
+    return requirements
+
+
+def wait_for_lint_config_dependencies(
+    root: Path,
+    *,
+    attempts: int = 6,
+    delay: timedelta = timedelta(seconds=10),
+    checker: PublicationChecker = publication_exists,
+    sleeper: Callable[[float], object] = time.sleep,
+) -> tuple[RegistryRequirement, ...]:
+    if attempts < 1:
+        message = "publication attempts must be at least one"
+        raise ValueError(message)
+    delay_seconds = delay.total_seconds()
+    if not math.isfinite(delay_seconds) or delay_seconds < 0:
+        message = "publication retry delay must be finite and non-negative"
+        raise ValueError(message)
+    requirements = lint_config_requirements(root)
+    missing = set(requirements)
+    last_errors: dict[RegistryRequirement, str] = {}
+    for attempt in range(attempts):
+        for requirement in tuple(sorted(missing)):
+            try:
+                available = checker(requirement)
+            except OSError as exc:
+                last_errors[requirement] = f"{type(exc).__name__}: {exc}"
+                continue
+            if available:
+                missing.remove(requirement)
+                last_errors.pop(requirement, None)
+        if not missing:
+            return requirements
+        if attempt + 1 < attempts:
+            _ = sleeper(delay_seconds)
+    rendered = ", ".join(
+        f"{requirement.name}@{requirement.version}"
+        + (f" ({last_errors[requirement]})" if requirement in last_errors else "")
+        for requirement in sorted(missing)
+    )
+    message = f"publications unavailable after {attempts} attempt(s): {rendered}"
+    raise ValueError(message)
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--root", type=Path, required=True)
+    parser.add_argument("--attempts", type=int, default=6)
+    parser.add_argument(
+        "--delay-seconds",
+        dest="delay",
+        type=_duration_from_seconds,
+        default=timedelta(seconds=10),
+    )
+    args = parser.parse_args(argv, namespace=_Args())
+    try:
+        requirements = wait_for_lint_config_dependencies(
+            args.root,
+            attempts=args.attempts,
+            delay=args.delay,
+        )
+    except (OSError, TypeError, ValueError) as exc:
+        sys.stderr.write(f"error: {exc}\n")
+        return 2
+    sys.stdout.write(f"verified {len(requirements)} exact compatibility-bundle publications\n")
+    return 0
+
+
+def _duration_from_seconds(value: str) -> timedelta:
+    return timedelta(seconds=float(value))
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

sarj_standards/libs/release/release_age.py

@@ -0,0 +1,218 @@
+from __future__ import annotations
+
+from concurrent.futures import ThreadPoolExecutor
+from dataclasses import dataclass
+from datetime import UTC, datetime, timedelta
+import json
+from typing import TYPE_CHECKING, NamedTuple, Protocol, Self
+from urllib.parse import quote
+from urllib.request import Request, urlopen
+
+from sarj_standards.libs.release._values import is_object_dict, string_object_dict
+
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Mapping
+    from pathlib import Path
+
+_SCOPED_PACKAGE_PARTS = 2
+
+
+class _PublicationTime(NamedTuple):
+    available: bool
+    published: datetime | None
+
+
+def load_exact_exclusions(path: Path) -> frozenset[str]:
+    try:
+        lines = path.read_text(encoding="utf-8").splitlines()
+    except OSError as exc:
+        msg = f"could not read release-age exclusions {path}: {exc}"
+        raise ValueError(msg) from exc
+    exclusions: set[str] = set()
+    for line_number, raw_line in enumerate(lines, start=1):
+        value = raw_line.partition("#")[0].strip()
+        if not value:
+            continue
+        name, separator, version = value.rpartition("@")
+        if not separator or not name or not version or (name.startswith("@") and "/" not in name):
+            msg = f"{path}:{line_number}: expected an exact package@version exclusion"
+            raise ValueError(msg)
+        exclusions.add(value)
+    return frozenset(exclusions)
+
+
+class PackumentFetcher(Protocol):
+    def __call__(self, package_name: str, /) -> Mapping[str, object]: ...
+
+
+@dataclass(frozen=True, slots=True, order=True)
+class PackageIdentity:
+    name: str
+    version: str
+
+
+@dataclass(frozen=True, slots=True)
+class ReleaseAgePolicy:
+    minimum_age: timedelta = timedelta(days=14)
+    exclusions: frozenset[str] = frozenset()
+
+    def __post_init__(self) -> None:
+        if self.minimum_age < timedelta(0):
+            msg = "minimum release age must be non-negative"
+            raise ValueError(msg)
+
+    @classmethod
+    def from_strings(cls, days_value: str | None, exclusions: str | None) -> Self:
+        raw_days = "14" if days_value is None else days_value
+        try:
+            parsed_days = int(raw_days, 10)
+        except ValueError as exc:
+            msg = "MIN_RELEASE_AGE_DAYS must be a non-negative integer"
+            raise ValueError(msg) from exc
+        if parsed_days < 0 or str(parsed_days) != raw_days.strip():
+            msg = "MIN_RELEASE_AGE_DAYS must be a non-negative integer"
+            raise ValueError(msg)
+        parsed_exclusions = frozenset(value for item in (exclusions or "").split(",") if (value := item.strip()))
+        return cls(timedelta(days=parsed_days), parsed_exclusions)
+
+
+@dataclass(frozen=True, slots=True, order=True)
+class ReleaseAgeFailure:
+    identity: PackageIdentity
+    detail: str
+
+    def __str__(self) -> str:
+        return f"{self.identity.name}@{self.identity.version}: {self.detail}"
+
+
+@dataclass(frozen=True, slots=True)
+class ReleaseAgeReport:
+    checked: tuple[PackageIdentity, ...]
+    failures: tuple[ReleaseAgeFailure, ...]
+
+    @property
+    def passed(self) -> bool:
+        return not self.failures
+
+
+def locked_registry_packages(lockfile: Path, policy: ReleaseAgePolicy) -> tuple[PackageIdentity, ...]:
+    packages_value = _load_object(lockfile).get("packages")
+    if packages_value is None:
+        return ()
+    packages = string_object_dict(packages_value, label="package-lock packages")
+    identities: set[PackageIdentity] = set()
+    for lock_path, metadata_value in packages.items():
+        name = _package_name(lock_path)
+        if name is None or not is_object_dict(metadata_value):
+            continue
+        metadata = string_object_dict(metadata_value, label=f"package metadata for {lock_path}")
+        version = metadata.get("version")
+        resolved = metadata.get("resolved")
+        if not isinstance(version, str) or not version:
+            continue
+        if isinstance(resolved, str) and not resolved.startswith("https://registry.npmjs.org/"):
+            msg = f"lockfile package {name}@{version} resolves outside registry.npmjs.org: {resolved}"
+            raise ValueError(msg)
+        identity = PackageIdentity(name, version)
+        if name not in policy.exclusions and f"{name}@{version}" not in policy.exclusions:
+            identities.add(identity)
+    return tuple(sorted(identities))
+
+
+def _load_object(path: Path) -> dict[str, object]:
+    try:
+        untyped: object = json.loads(path.read_text(encoding="utf-8"))  # pyright: ignore[reportAny]
+    except (OSError, json.JSONDecodeError) as exc:
+        msg = f"could not read npm lockfile {path}: {exc}"
+        raise ValueError(msg) from exc
+    return string_object_dict(untyped, label="npm lockfile")
+
+
+def _package_name(lock_path: str) -> str | None:
+    marker = "node_modules/"
+    if marker not in lock_path:
+        return None
+    tail = lock_path.rpartition(marker)[2]
+    parts = tail.split("/")
+    if not parts[0]:
+        return None
+    if parts[0].startswith("@"):
+        return "/".join(parts[:_SCOPED_PACKAGE_PARTS]) if len(parts) >= _SCOPED_PACKAGE_PARTS and parts[1] else None
+    return parts[0]
+
+
+def fetch_npm_packument(package_name: str) -> Mapping[str, object]:
+    url = f"https://registry.npmjs.org/{quote(package_name, safe='')}"
+    request = Request(url, headers={"Accept": "application/json"})
+    with urlopen(request, timeout=15) as response:  # ruff: ignore[suspicious-url-open-usage]  # pyright: ignore[reportAny] -- fixed trusted origin
+        untyped: object = json.load(response)  # pyright: ignore[reportAny]
+    return string_object_dict(untyped, label=f"npm registry response for {package_name}")
+
+
+def _utc_now() -> datetime:
+    return datetime.now(UTC)
+
+
+def check_lockfile_release_age(
+    lockfile: Path,
+    policy: ReleaseAgePolicy | None = None,
+    *,
+    fetcher: PackumentFetcher = fetch_npm_packument,
+    clock: Callable[[], datetime] = _utc_now,
+    concurrency: int = 12,
+) -> ReleaseAgeReport:
+    if concurrency < 1:
+        msg = "release-age concurrency must be at least one"
+        raise ValueError(msg)
+    now = clock()
+    if now.tzinfo is None:
+        msg = "release-age clock must return a timezone-aware datetime"
+        raise ValueError(msg)
+    now = now.astimezone(UTC)
+    effective_policy = ReleaseAgePolicy() if policy is None else policy
+    identities = locked_registry_packages(lockfile, effective_policy)
+    cutoff = now - effective_policy.minimum_age
+
+    def check_one(identity: PackageIdentity) -> ReleaseAgeFailure | None:
+        return _check_identity(identity, cutoff=cutoff, now=now, fetcher=fetcher)
+
+    with ThreadPoolExecutor(max_workers=min(concurrency, max(1, len(identities)))) as executor:
+        checked = executor.map(check_one, identities)
+        failures = tuple(sorted(failure for failure in checked if failure is not None))
+    return ReleaseAgeReport(identities, failures)
+
+
+def _check_identity(
+    identity: PackageIdentity,
+    *,
+    cutoff: datetime,
+    now: datetime,
+    fetcher: PackumentFetcher,
+) -> ReleaseAgeFailure | None:
+    available, published = _publication_time(fetcher(identity.name), identity.version)
+    if not available:
+        return ReleaseAgeFailure(identity, "publication time unavailable")
+    if published is None:
+        return ReleaseAgeFailure(identity, "unknown days old")
+    if published > cutoff:
+        age_days = (now - published).total_seconds() / timedelta(days=1).total_seconds()
+        return ReleaseAgeFailure(identity, f"{age_days:.1f} days old")
+    return None
+
+
+def _publication_time(packument: Mapping[str, object], version: str) -> _PublicationTime:
+    time_value = packument.get("time")
+    if not is_object_dict(time_value):
+        return _PublicationTime(available=False, published=None)
+    published = string_object_dict(time_value, label="npm publication times").get(version)
+    if not isinstance(published, str):
+        return _PublicationTime(available=False, published=None)
+    try:
+        parsed = datetime.fromisoformat(published)
+    except ValueError:
+        return _PublicationTime(available=True, published=None)
+    return _PublicationTime(
+        available=True,
+        published=parsed.astimezone(UTC) if parsed.tzinfo is not None else None,
+    )