code-standards 7.0.0__py3-none-any.whl

sarj_standards/libs/release/__init__.py

@@ -0,0 +1,98 @@
+from sarj_standards.libs.release.artifacts import (
+    required_artifact_paths,
+    verify_built_package,
+    verify_package_tarball,
+    verify_python_wheel_license,
+)
+from sarj_standards.libs.release.causality import (
+    CausalityViolation,
+    ReleaseCausalityReport,
+    check_release_causality,
+)
+from sarj_standards.libs.release.changes import changed_release_targets, pending_release_targets
+from sarj_standards.libs.release.process import (
+    ProcessFailureError,
+    ProcessResult,
+    ProcessRunner,
+    credential_free_environment,
+    run_build_process,
+    run_process,
+    run_process_environment,
+)
+from sarj_standards.libs.release.publish import PublishTarget, publish_target
+from sarj_standards.libs.release.release_age import (
+    PackageIdentity,
+    PackumentFetcher,
+    ReleaseAgeFailure,
+    ReleaseAgePolicy,
+    ReleaseAgeReport,
+    check_lockfile_release_age,
+    fetch_npm_packument,
+    load_exact_exclusions,
+    locked_registry_packages,
+)
+from sarj_standards.libs.release.tags import (
+    RELEASE_TARGETS,
+    ReleaseTarget,
+    ReleaseTargetId,
+    TagSyncResult,
+    ValidatedReleaseTag,
+    create_release_tags,
+    missing_remote_release_tags,
+    read_manifest_version,
+    validate_release_tag,
+    verify_remote_release_tags,
+)
+from sarj_standards.libs.release.typescript import (
+    PackedArtifact,
+    ReleaseMode,
+    check_typescript,
+    pack_typescript,
+    run_typescript_release,
+)
+
+
+__all__ = (
+    "RELEASE_TARGETS",
+    "CausalityViolation",
+    "PackageIdentity",
+    "PackedArtifact",
+    "PackumentFetcher",
+    "ProcessFailureError",
+    "ProcessResult",
+    "ProcessRunner",
+    "PublishTarget",
+    "ReleaseAgeFailure",
+    "ReleaseAgePolicy",
+    "ReleaseAgeReport",
+    "ReleaseCausalityReport",
+    "ReleaseMode",
+    "ReleaseTarget",
+    "ReleaseTargetId",
+    "TagSyncResult",
+    "ValidatedReleaseTag",
+    "changed_release_targets",
+    "check_lockfile_release_age",
+    "check_release_causality",
+    "check_typescript",
+    "create_release_tags",
+    "credential_free_environment",
+    "fetch_npm_packument",
+    "load_exact_exclusions",
+    "locked_registry_packages",
+    "missing_remote_release_tags",
+    "pack_typescript",
+    "pending_release_targets",
+    "publish_target",
+    "read_manifest_version",
+    "required_artifact_paths",
+    "run_build_process",
+    "run_process",
+    "run_process_environment",
+    "run_typescript_release",
+    "validate_release_tag",
+    "verify_built_package",
+    "verify_package_tarball",
+    "verify_python_wheel_license",
+    "verify_remote_release_tags",
+)

sarj_standards/libs/release/_values.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+from typing import TypeIs
+
+
+def is_object_list(value: object) -> TypeIs[list[object]]:
+    return isinstance(value, list)
+
+
+def is_object_dict(value: object) -> TypeIs[dict[object, object]]:
+    return isinstance(value, dict)
+
+
+def string_object_dict(value: object, *, label: str) -> dict[str, object]:
+    if not is_object_dict(value):
+        msg = f"{label} must contain an object or table"
+        raise TypeError(msg)
+    result: dict[str, object] = {}
+    for key, item in value.items():
+        if not isinstance(key, str):
+            msg = f"{label} contains a non-string key"
+            raise TypeError(msg)
+        result[key] = item
+    return result

sarj_standards/libs/release/artifacts.py

@@ -0,0 +1,191 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path, PurePosixPath
+import tarfile
+from typing import TYPE_CHECKING, NamedTuple
+import zipfile
+
+from sarj_standards.libs.release._values import is_object_dict, is_object_list, string_object_dict
+
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping, Sequence
+
+
+type JsonValue = str | int | float | bool | list[JsonValue] | dict[str, JsonValue] | None
+_INSTALL_LIFECYCLE_SCRIPTS = frozenset({"preinstall", "install", "postinstall", "prepare"})
+
+
+class _InspectedMembers(NamedTuple):
+    found: set[str]
+    identity_verified: bool
+
+
+def _json_value(value: object) -> JsonValue:
+    match value:
+        case None | str() | int() | float() | bool():
+            return value
+        case _ if is_object_list(value):
+            return [_json_value(item) for item in value]
+        case _ if is_object_dict(value):
+            return {key: _json_value(item) for key, item in string_object_dict(value, label="JSON").items()}
+        case _:
+            msg = "JSON contains an unsupported value"
+            raise TypeError(msg)
+
+
+def required_artifact_paths(package_json: Mapping[str, object]) -> tuple[str, ...]:
+    candidates: list[str] = []
+    for field in ("main", "module", "types"):
+        candidates.extend(_exported_paths(_json_value(package_json.get(field))))
+    candidates.extend(_exported_paths(_json_value(package_json.get("exports"))))
+    return tuple(dict.fromkeys(_safe_artifact_path(path) for path in candidates))
+
+
+def _exported_paths(value: JsonValue) -> tuple[str, ...]:
+    match value:
+        case str():
+            return (value,)
+        case list():
+            return tuple(path for item in value for path in _exported_paths(item))
+        case dict():
+            return tuple(path for item in value.values() for path in _exported_paths(item))
+        case _:
+            return ()
+
+
+def _safe_artifact_path(value: str) -> str:
+    normalized = value.removeprefix("./")
+    path = PurePosixPath(normalized)
+    if not normalized or path.is_absolute() or ".." in path.parts or path.as_posix() != normalized:
+        msg = f"unsafe exported entry point: {value}"
+        raise ValueError(msg)
+    return normalized
+
+
+def load_package_json(package_root: Path) -> dict[str, JsonValue]:
+    manifest = package_root / "package.json"
+    try:
+        untyped: object = json.loads(manifest.read_text(encoding="utf-8"))  # pyright: ignore[reportAny]
+        value = _json_value(untyped)
+    except (OSError, json.JSONDecodeError) as exc:
+        msg = f"could not read {manifest}: {exc}"
+        raise ValueError(msg) from exc
+    if not isinstance(value, dict):
+        msg = f"{manifest} must contain a JSON object"
+        raise TypeError(msg)
+    return value
+
+
+def verify_built_package(package_root: Path) -> tuple[str, ...]:
+    required = required_artifact_paths(load_package_json(package_root))
+    if not required:
+        msg = "package.json declares no publishable entry points"
+        raise ValueError(msg)
+    resolved_root = package_root.resolve()
+    for relative in required:
+        if PurePosixPath(relative).parts[0] != "dist":
+            msg = f"exported entry point must live under dist/: {relative}"
+            raise ValueError(msg)
+        artifact = package_root / relative
+        try:
+            artifact.resolve().relative_to(resolved_root)
+        except (OSError, ValueError) as exc:
+            msg = f"exported entry point escapes the package root: {relative}"
+            raise ValueError(msg) from exc
+        if artifact.is_symlink() or not artifact.is_file() or artifact.stat().st_size == 0:
+            msg = f"exported entry point is missing or empty: {relative}"
+            raise ValueError(msg)
+    return required
+
+
+def verify_package_tarball(
+    tarball: Path,
+    required: Sequence[str],
+    *,
+    expected_name: str | None = None,
+    expected_version: str | None = None,
+) -> tuple[str, ...]:
+    expected = {"package/LICENSE", *(f"package/{path}" for path in required)}
+    try:
+        with tarfile.open(tarball, mode="r:gz") as archive:
+            found, identity_verified = _inspect_members(
+                archive,
+                expected,
+                expected_name=expected_name,
+                expected_version=expected_version,
+            )
+    except (OSError, tarfile.TarError) as exc:
+        msg = f"could not inspect package archive {tarball}: {exc}"
+        raise ValueError(msg) from exc
+    missing = sorted(expected - found)
+    if missing:
+        msg = f"packed artifact omits exported entry point: {missing[0].removeprefix('package/')}"
+        raise ValueError(msg)
+    if (expected_name is not None or expected_version is not None) and not identity_verified:
+        msg = "package archive omits package/package.json identity"
+        raise ValueError(msg)
+    return tuple(required)
+
+
+def verify_python_wheel_license(wheel: Path) -> None:
+    try:
+        with zipfile.ZipFile(wheel) as archive:
+            licenses = [name for name in archive.namelist() if PurePosixPath(name).name == "LICENSE"]
+            if not licenses or any(not archive.read(name) for name in licenses):
+                msg = f"wheel omits a non-empty LICENSE: {wheel.name}"
+                raise ValueError(msg)
+    except zipfile.BadZipFile as exc:
+        msg = f"could not inspect wheel {wheel.name}"
+        raise ValueError(msg) from exc
+
+
+def _inspect_members(
+    archive: tarfile.TarFile,
+    expected: set[str],
+    *,
+    expected_name: str | None,
+    expected_version: str | None,
+) -> _InspectedMembers:
+    found: set[str] = set()
+    identity_verified = False
+    for member in archive.getmembers():
+        path = PurePosixPath(member.name)
+        if path.is_absolute() or ".." in path.parts or not path.parts or path.parts[0] != "package":
+            msg = f"unsafe path in package archive: {member.name}"
+            raise ValueError(msg)
+        if member.issym() or member.islnk():
+            msg = f"links are forbidden in package archive: {member.name}"
+            raise ValueError(msg)
+        if member.isfile() and member.name.endswith(".map"):
+            msg = f"source maps are forbidden in package archive: {member.name}"
+            raise ValueError(msg)
+        if member.name == "package/package.json" and member.isfile():
+            manifest_file = archive.extractfile(member)
+            if manifest_file is None:
+                msg = "could not read package/package.json from package archive"
+                raise ValueError(msg)
+            try:
+                manifest: object = json.load(manifest_file)  # pyright: ignore[reportAny]
+            except json.JSONDecodeError as exc:
+                msg = "package archive contains invalid package/package.json"
+                raise ValueError(msg) from exc
+            manifest_data = string_object_dict(manifest, label="packed package.json")
+            for field, expected_value in (("name", expected_name), ("version", expected_version)):
+                if expected_value is not None and manifest_data.get(field) != expected_value:
+                    msg = f"packed package {field} does not match source manifest"
+                    raise ValueError(msg)
+            identity_verified = True
+            scripts = manifest_data.get("scripts")
+            if is_object_dict(scripts):
+                dangerous = _INSTALL_LIFECYCLE_SCRIPTS.intersection(scripts)
+                if dangerous:
+                    msg = f"install lifecycle script is forbidden in package archive: {min(dangerous)}"
+                    raise ValueError(msg)
+        if member.name in expected:
+            if not member.isfile() or member.size == 0:
+                msg = f"packed entry point is missing, empty, or not a regular file: {member.name}"
+                raise ValueError(msg)
+            found.add(member.name)
+    return _InspectedMembers(found, identity_verified)

sarj_standards/libs/release/causality.py

@@ -0,0 +1,80 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from .changes import changed_release_targets
+from .process import ProcessRunner, run_process
+from .tags import RELEASE_ARTIFACT_FILES, RELEASE_ARTIFACT_PREFIXES, RELEASE_TARGETS
+
+
+_DISPLAY_PATH_LIMIT = 3
+
+
+@dataclass(frozen=True, slots=True)
+class CausalityViolation:
+    target: str
+    manifest: Path
+    version_field: str
+    changed_paths: tuple[str, ...]
+
+    def render(self) -> str:
+        paths = ", ".join(self.changed_paths[:_DISPLAY_PATH_LIMIT])
+        suffix = (
+            f" (+{len(self.changed_paths) - _DISPLAY_PATH_LIMIT} more)"
+            if len(self.changed_paths) > _DISPLAY_PATH_LIMIT
+            else ""
+        )
+        return (
+            f"{self.target}: bump {self.version_field} in {self.manifest}; publishable files changed: {paths}{suffix}"
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class ReleaseCausalityReport:
+    before: str
+    after: str
+    changed_targets: tuple[str, ...]
+    bumped_targets: tuple[str, ...]
+    violations: tuple[CausalityViolation, ...]
+
+    @property
+    def ok(self) -> bool:
+        return not self.violations
+
+
+def check_release_causality(
+    root: Path,
+    *,
+    before: str,
+    after: str,
+    runner: ProcessRunner = run_process,
+) -> ReleaseCausalityReport:
+    result = runner(("git", "diff", "--name-only", "-z", before, after, "--"), cwd=root, capture_output=True)
+    changed_paths = tuple(sorted(path for path in result.stdout.split("\0") if path))
+    bumped = changed_release_targets(root, before=before, after=after, runner=runner)
+    by_target = {
+        name: tuple(path for path in changed_paths if _belongs_to_artifact(name, path=path)) for name in RELEASE_TARGETS
+    }
+    changed_targets = tuple(name for name, paths in by_target.items() if paths)
+    violations = tuple(
+        CausalityViolation(
+            name,
+            RELEASE_TARGETS[name].manifest,
+            'top-level "version"' if RELEASE_TARGETS[name].format == "json" else "[project].version",
+            by_target[name],
+        )
+        for name in changed_targets
+        if not bumped[name]
+    )
+    return ReleaseCausalityReport(
+        before,
+        after,
+        changed_targets,
+        tuple(name for name, changed in bumped.items() if changed),
+        violations,
+    )
+
+
+def _belongs_to_artifact(target: str, *, path: str) -> bool:
+    return path in RELEASE_ARTIFACT_FILES[target] or path.startswith(RELEASE_ARTIFACT_PREFIXES[target])

sarj_standards/libs/release/changes.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+
+import re
+from typing import TYPE_CHECKING
+
+from sarj_standards.libs.release.process import ProcessRunner, run_process
+from sarj_standards.libs.release.registry import PublicationChecker, publication_exists, target_requirement
+from sarj_standards.libs.release.tags import RELEASE_TARGETS
+
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+    from pathlib import Path
+
+
+_ADDED_JSON_VERSION = re.compile(r'(?m)^\+\s*"version"\s*:')
+_ADDED_TOML_VERSION = re.compile(r"(?m)^\+version\s*=")
+
+
+def changed_release_targets(
+    root: Path,
+    *,
+    before: str,
+    after: str,
+    runner: ProcessRunner = run_process,
+) -> Mapping[str, bool]:
+    changed: dict[str, bool] = {}
+    for name, target in RELEASE_TARGETS.items():
+        result = runner(
+            ("git", "diff", "--no-color", before, after, "--", target.manifest.as_posix()),
+            cwd=root,
+            capture_output=True,
+        )
+        pattern = _ADDED_JSON_VERSION if target.format == "json" else _ADDED_TOML_VERSION
+        changed[name] = pattern.search(result.stdout) is not None
+    return changed
+
+
+def pending_release_targets(
+    root: Path,
+    *,
+    before: str,
+    after: str,
+    runner: ProcessRunner = run_process,
+    checker: PublicationChecker = publication_exists,
+) -> Mapping[str, bool]:
+    _ = changed_release_targets(root, before=before, after=after, runner=runner)
+    return {name: not checker(target_requirement(root, name)) for name in RELEASE_TARGETS}

sarj_standards/libs/release/process.py

@@ -0,0 +1,128 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+import os
+import subprocess  # ruff: ignore[suspicious-subprocess-import] -- Centralized argv-only process adapter; shell execution is never enabled.
+import tempfile
+from typing import TYPE_CHECKING, Protocol
+
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+    from pathlib import Path
+
+
+_BLOCKED_CREDENTIAL_NAMES = frozenset(
+    {"DOCKER_CONFIG", "GIT_ASKPASS", "NETRC", "NPM_CONFIG_USERCONFIG", "PIP_CONFIG_FILE", "SSH_ASKPASS"}
+)
+
+
+@dataclass(frozen=True, slots=True)
+class ProcessResult:
+    returncode: int
+    stdout: str = ""
+    stderr: str = ""
+
+    def __post_init__(self) -> None:
+        if type(self.returncode) is not int:
+            msg = "process return code must be an integer"
+            raise TypeError(msg)
+        if type(self.stdout) is not str:
+            msg = "process stdout must be text"
+            raise TypeError(msg)
+        if type(self.stderr) is not str:
+            msg = "process stderr must be text"
+            raise TypeError(msg)
+
+
+class ProcessRunner(Protocol):
+    def __call__(
+        self,
+        argv: tuple[str, ...],
+        *,
+        cwd: Path,
+        capture_output: bool = False,
+    ) -> ProcessResult: ...
+
+
+class ProcessFailureError(RuntimeError):
+    argv: tuple[str, ...]
+    returncode: int
+
+    def __init__(self, argv: tuple[str, ...], returncode: int) -> None:
+        self.argv = argv
+        self.returncode = returncode
+        super().__init__(f"{argv[0]} {argv[1] if len(argv) > 1 else ''} failed with exit code {returncode}")
+
+
+def run_process(
+    argv: tuple[str, ...],
+    *,
+    cwd: Path,
+    capture_output: bool = False,
+) -> ProcessResult:
+    return run_process_environment(argv, cwd=cwd, capture_output=capture_output, environment=None)
+
+
+def run_process_environment(
+    argv: tuple[str, ...],
+    *,
+    cwd: Path,
+    capture_output: bool = False,
+    environment: Mapping[str, str] | None,
+) -> ProcessResult:
+    completed = subprocess.run(  # ruff: ignore[subprocess-without-shell-equals-true] -- argv is passed directly and shell remains disabled.
+        argv,
+        cwd=cwd,
+        check=False,
+        env=None if environment is None else dict(environment),
+        text=True,
+        stdout=subprocess.PIPE if capture_output else None,
+        stderr=None,
+    )
+    result = ProcessResult(completed.returncode, completed.stdout or "")
+    if result.returncode != 0:
+        raise ProcessFailureError(argv, result.returncode)
+    return result
+
+
+def credential_free_environment(environment: Mapping[str, str] | None = None) -> dict[str, str]:
+    source = os.environ if environment is None else environment  # ruff: ignore[banned-api] -- deliberate child-process boundary
+    blocked_fragments = ("TOKEN", "SECRET", "PASSWORD", "CREDENTIAL", "API_KEY", "AUTH")
+    blocked_prefixes = ("AWS_", "AZURE_", "GOOGLE_", "TWINE_", "UV_PUBLISH_", "ACTIONS_ID_TOKEN_")
+    return {
+        name: value
+        for name, value in source.items()
+        if name.upper() not in _BLOCKED_CREDENTIAL_NAMES
+        and not name.upper().startswith(blocked_prefixes)
+        and not any(fragment in name.upper() for fragment in blocked_fragments)
+    }
+
+
+def run_build_process(
+    argv: tuple[str, ...],
+    *,
+    cwd: Path,
+    capture_output: bool = False,
+) -> ProcessResult:
+    with tempfile.TemporaryDirectory(prefix="sarj-build-home-") as home:
+        environment = credential_free_environment()
+        environment.update(
+            {
+                "GIT_CONFIG_GLOBAL": os.devnull,
+                "HOME": home,
+                "USERPROFILE": home,
+                "APPDATA": home,
+                "LOCALAPPDATA": home,
+                "NETRC": os.devnull,
+                "NPM_CONFIG_USERCONFIG": os.devnull,
+                "PIP_CONFIG_FILE": os.devnull,
+                "XDG_CONFIG_HOME": home,
+            }
+        )
+        return run_process_environment(
+            argv,
+            cwd=cwd,
+            capture_output=capture_output,
+            environment=environment,
+        )

sarj_standards/libs/release/publish.py

@@ -0,0 +1,85 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from tempfile import TemporaryDirectory
+from types import MappingProxyType
+from typing import TYPE_CHECKING, Literal
+
+from sarj_standards.libs.release.artifacts import verify_python_wheel_license
+from sarj_standards.libs.release.process import ProcessRunner, run_build_process, run_process
+from sarj_standards.libs.release.typescript import run_typescript_release
+
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+
+PublishTarget = Literal["typescript", "bootstrap", "python", "sql", "iac", "standards", "tsconfig", "docs-ui"]
+_EXPECTED_PYTHON_ARTIFACTS = 1
+_PYTHON_TARGETS: Mapping[str, str] = MappingProxyType(
+    {
+        "bootstrap": "bootstrap",
+        "python": "python",
+        "sql": "sql",
+        "iac": "iac",
+        "standards": "standards",
+    }
+)
+
+
+def publish_target(root: Path, target: PublishTarget, *, runner: ProcessRunner = run_process) -> None:
+    resolved = root.resolve()
+    build_runner = run_build_process if runner is run_process else runner
+    if target == "typescript":
+        _ = run_typescript_release("publish", resolved / "packages" / "typescript", runner=runner)
+        return
+    if target in {"tsconfig", "docs-ui"}:
+        cwd = resolved / "packages" / target
+        with TemporaryDirectory(prefix=f"sarj-{target}-release-") as temporary:
+            destination = Path(temporary)
+            result = build_runner(
+                ("npm", "pack", "--json", "--pack-destination", str(destination)),
+                cwd=cwd,
+                capture_output=True,
+            )
+            artifact = destination / _npm_pack_filename(result.stdout)
+            if not artifact.is_file() or artifact.stat().st_size == 0:
+                msg = f"npm pack did not create its reported artifact: {artifact.name}"
+                raise ValueError(msg)
+            runner(("npm", "publish", str(artifact), "--access", "public", "--ignore-scripts"), cwd=cwd)
+        return
+    package = _PYTHON_TARGETS.get(target)
+    if package is None:
+        msg = f"unsupported release target: {target}"
+        raise ValueError(msg)
+    cwd = resolved / "packages" / package
+    with TemporaryDirectory(prefix=f"sarj-{package}-release-") as temporary:
+        destination = Path(temporary)
+        build_runner(("uv", "build", "--wheel", "--out-dir", str(destination)), cwd=cwd)
+        artifacts = tuple(sorted(destination.glob("*.whl")))
+        if len(artifacts) != _EXPECTED_PYTHON_ARTIFACTS or any(
+            not artifact.is_file() or artifact.stat().st_size == 0 for artifact in artifacts
+        ):
+            msg = f"uv build did not create exactly one wheel for {target}"
+            raise ValueError(msg)
+        verify_python_wheel_license(artifacts[0])
+        runner(("uv", "publish", *(str(artifact) for artifact in artifacts)), cwd=cwd)
+
+
+def _npm_pack_filename(output: str) -> str:
+    decoder = json.JSONDecoder()
+    for index in range(len(output) - 1, -1, -1):
+        if output[index] != "[":
+            continue
+        try:
+            report, _ = decoder.raw_decode(output[index:])  # pyright: ignore[reportAny]
+        except json.JSONDecodeError:
+            continue
+        if not isinstance(report, list) or not report or not isinstance(report[0], dict):
+            continue
+        filename = report[0].get("filename")  # pyright: ignore[reportUnknownMemberType,reportUnknownVariableType]
+        if isinstance(filename, str) and Path(filename).name == filename and filename.endswith(".tgz"):
+            return filename
+    msg = "npm pack returned no safe artifact filename"
+    raise ValueError(msg)